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Introduction 
Howdy Folks, 


I've been working in the software business for over 30 years but until recently, hadn't been playing directly 
with Micro Processors. When | bought a Raspberry PI and then an Arduino, I'm afraid | got hooked. In 
my house | am surrounded by computers of all shapes, sizes and capacities ... any one of them with 
orders of magnitude more power than any of these small devices ... however, | still found myself 
fascinated. 


When | stumbled across the ESP8266 in early 2015, it piqued my interest. | hadn't touched C 
programming in decades (I'm a Java man these days). As | started to read what was available in the way 
of documentation from the excellent community surrounding the device, | found that there were only small 
pockets of knowledge. The best source of information was (and still is) the official PDFs for the SDK from 
Espressif (the makers of the ESP8266) but even that is quite "light" on examples and background. As | 
studied the device, | started to make notes and my pages of notes continued to grow and grow. About a 
year later, the ESP32 found its way into my possession. 


This book (if we want to call it that) is my collated and polished version of those notes. Rather than keep 
them to myself, | offer them to all of us in the ESP32 community in the hope that they will be of some 
value. My plan is to continue to update this work as we all learn more and share what we find in the 
community forums. As such, | will re-release the work at regular intervals so please check back at the 
book's home page for the latest. 


As you read, make sure that you fully understand that there are undoubtedly inaccuracies, errors in my 
understanding and errors in my writing. Only by feedback and time will we be able to correct those. 
Please forgive the grammatical errors and spelling mistakes that my spell checker hasn't caught. 


Please don't email me directly with technical questions. Instead, let us use the forum and ask and answer 
the questions as a great community of ESP32 minded enthusiasts, hobbyists and professionals. 





Neil Kolbaw 
Texas, ASA 
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Important Documentation Notes — ESP8266 and ESP32 

At the start of 2015 | released a book of notes on ESP8266 and the ESP32 was still a 
long way off. At the time we knew very little about the ESP32 and my initial thinking 
was that | would cover both the ESP8266 and the ESP32 in one book. Now that we 
have the ESP32 it has become obvious that the distinctions between that device and 
the ESP8266 are far too great to be accommodated in one document. If we tried to 
merge the two we would be forever reading that "this applies to ESP8266" and "that 
applies to ESP32". As such, this book is explicitly for the ESP32. However ... there is 
currently a catch. Since there is indeed a goodly amount of material that is common to 
both devices, rather than start from scratch on a new book, | have taken the ESP8266 
book as a base and am working through this book reworking it for ESP32 exclusivity. 
This is a work in progress. | have added the majority of what is new in ESP32 but 
haven't yet gotten to removing much of what is ESP8266 specific. As such, when your 
read this work, you will have to pay attention because some of the story is ESP8266 
only and will either be removed or reworked over the period ahead. 


Overview 

A micro controller is an integrated circuit that is capable of running programs. There are 
many instances of those on the market today from a variety of manufacturers. The 
prices of these micro controllers keeps falling. In the hobbyist market, an open source 
architecture called "Arduino" that uses the Atmel range of processors has caught the 
imagination of countless folks. The boards containing these Atmel chips combined with 
a convention for connections and also a free set of development tools has lowered the 
entry point for playing with electronics to virtually nill. Unlike a PC, these processors are 
extremely low end with low amounts of ram and storage capabilities. They won't be 
replacing the desktop or laptop any time soon. For those who want more "oomph" in 
their processors, the folks over at Raspberry PI have developed a very cheap (~$45) 
board that is based on the ARM processors that has much more memory and uses 
micro SD for persistent data storage. These devices run a variant of the Linux 
operating system. I'm not going to talk further about the Raspberry PI as it is in the 
class of "computer" as opposed to microprocessor. 


These micro controllers and architectures are great and there will always be a place for 
them. However, there is a catch ... and that is networking. These devices have an 
amazing set of capabilities including direct electrical inputs and outputs (GPIOs) and 
support for a variety of protocols including SPI, 12C, UART and more, however, few of 
them so far come with wireless networking included. 
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No question (in my mind) that the Arduino has captured everyone's attention. The 
Arduino is based on the Atmel chips and has a variety of physical sizes in its open 
hardware footprints. The primary micro controller used is the ATmega328. One can 
find instances of these raw processors on eBay for under $2 with fully constructed 
boards containing them for under $3. This is 10-20 times cheaper than the Raspberry 
Pl. Of course, one gets dramatically less than the Raspberry PI so comparison can 
become odd ... however if what one wants to do is tinker with electronics or make some 
simple devices that connect to LEDs, switches or sensors, then the functional features 
needed become closer. 


Between them, the Arduino and the Raspberry PI appear to have all the needs covered. 
If that were the case, this would be a very short book. Let us add the twist that we 
started with ... wireless networking. To have a device move a robot chassis or flash 
LED patterns or make some noises or read data from a sensor and beep when the 
temperature gets too high ... these are all great and worthy projects. However, we are 
all very much aware of the value of the Internet. Our computers are Internet connected, 
our phones are connected, we watch TV (Netflix) over the Internet, we play games over 
the Internet, we socialize (??) over the Internet ... and so on. The Internet has become 
such a basic commodity that we would laugh if someone offered us a new computer or 
a phone that lacked the ability to go "on-line". 


Now imagine what a micro controller with native wireless Internet could do for us? This 
would be a processor which could run applications as well as or better than an Arduino, 
which would have GPIO and hardware protocol support, would have RAM and flash 
memory ... but would have the killer new feature that it would also be able to form 
Internet connections. And that ... simply put ... is what the ESP32 device is. It is an 
alternative microprocessor to the ones already mentioned but also has WiFi and TCP/IP 
(Transmission Control Protocol / Internet Protocol) support already built in. What is 
more, it is also not much more expensive than an Arduino. Searching eBay, we find 
ESP32 modules around the $6 price point. 


The ESP32 

The ESP32 is the name of a micro controller designed by Espressif Systems. Espressif 
is a Chinese company based out of Shanghai. The ESP32 advertises itself as a self- 
contained WiFi networking solution offering itself as a bridge from existing micro 
controllers to WiFi ... and ... is also capable of running self contained applications. 


Volume production of the ESP32 didn't start until the late of 2016 which means that, in 
the scheme of things, this is a brand new entry in the line-up of processors. And ... in 
our technology hungry world, new commonly equates to interesting. A couple of years 
after IC production, 3 party OEMs are taking these chips and building "breakout 
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boards" for them. If | were to hand you a raw ESP32 straight from the factory, it is 
unlikely we would know what to do with one. They are very tiny and virtually impossible 
for hobbyists to attach wires to allow them to be plugged into breadboards. Thankfully, 
OEMs bulk purchase the ICs, design basic circuits, design printed circuit boards and 
construct pre-made boards with the ICs pre-attached immediately ready for our use. It 
is these boards that capture our interest and that we can buy for a few dollars on eBay. 


There are a variety of board styles available but from a programming perspective, they 
are all the same. 


The ESP32 specification 

When we look at a new electronic device, we are always interested in its specifications. 
This is the set of characteristics as described by the manufacturer. Sometimes it is 
immediately obvious to us what a specification item means and for others, it takes some 
time to appreciate its ramifications. Here is a summary list of the core ESP32 items: 


















































Attribute Details 
Voltage 3.3V 

Current consumption Unknown 
Flash memory attachable Module based 
Processor Tensilica L108 32 bit 
Processor speed Dual 160MHz 
RAM 520K 

GPIOs 34 

Analog to Digital 7 

802.11 support 11b/g/n/e/i 
Bluetooth BLE 
Maximum concurrent TCP connections 16 

SPI 3 

I2S 2 

I2C 2 

UART 3 














The ESP32 is a dual core processor running the Xtensa LX6 instructions. The cores 
are called "PRo_ cpu" and "App cpu". 


The question of determining how long an ESP32 can run on batteries is an interesting 
one. The current consumption is far from constant. When transmitting at full power, it 
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can consume 260mA but when in a deep sleep, it only need 20UA. That is quite a 
difference. This means that the run-time of an ESP32 on a fixed current reservoir is not 
just a function of time but also of what it is doing during that time ... and that is a 
function of the program deployed upon it. 


The ESP32 is designed to be used with a partner memory module and this is most 
commonly flash memory. Most of the modules come with some flash associated with 
them. Realize that flash has a finite number of erases per page before something fails. 
They are rated at about 10,000 erases. This is not normally an issue for configuration 
change writes or daily log writes ... but if your application is continually writing new data 
extremely fast, then this may be an issue and your flash memory will fail. 


Modules 
At the time of writing, the ESP32 has only recently become generally available, as such 
there are still relatively few modules to be bought. 


ESP-WROOM-32 

A module called the ESP-WWROOM-32 is available from Espressif that contains an 
ESP32 plus accompanying supporting hardware such as flash memory. Don't mistake 
this for a breadboard friendly device ... this is much more oriented to those with good 
electronics skills that wish to embed an ESP32 in a specific project. The module is only 
18mm x 25.5mm and has pin spacings at the 1.27mm pitch. This is an extremely small 
spacing. 





The fantastic web site called PIGHIXXX provides the most top quality pin-out images | 
have ever seen. Please visit their site. They have pin-outs for almost every 
conceivable device | have ever wanted to know about. 


Here is a schematic of the current device: 
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See also: 


. ESP-WROOM-32 Datasheet 
. Adafruit — seller of devices in US 
. ESP-WROOM-32 Home Page 











ESP32-DevKitC 

With the release of the ESP32, Espressif have released their own module for exposing 
the ESP32 to more consumers. The board they have produced is called the "ESP32- 
Devkit" and is considered bread-board friendly. 
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The board contains headers for the ESP32 as well as a micro USB adapter and two 
buttons called enable and boot. These buttons can be used to "flash" or "download" 


new application code into the module. To perform this task, hold the "1 
while pressing and releasing " 


The pin out of the module is shown in the following image: 


i 


UART 
@ sy 


Page 44 





© [A0<i cro] GPIO3E 
@ [ani cra] GPIO39 
@ [a0 cre] GPIO34 
© (x01 cr (GPIO3S 





‘UIRTS: 
[5v) 


Boot". 








(GPIOT | UOTX — 
(GPIO3 | UORX — 
'GPIO19 |vsei miso 
(GPIOS | (vsr1s5 | 


EN" button down 





To reboot the device, pulse En low. If cproo is high, the device will normal boot while if 
GPro0 Is low, it will boot into flash mode allowing us to upload a new application into the 
device's flash storage. 


See also: 


ESP32-DevkKitC — Getting Started Guide 
ESP32-DevkKitC home page 
Adafruit reseller 








ESP-WROVER-KIT 


To be written ... am awaiting the formal Espressif release slated for the end of 
February/March. 





See also: 


ESP-WROVER-KIT Home Page 
Adafruit reseller 





The SparkFun ESP32 thing 
SparkFun make an ESP32 board called the "ESP32 Thing”. 
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One of the distinguishing features of this board is the built in battery charger socket. 
We can use this board with a LIPO battery and charge that battery at the same time. 











The width of the Sparkfun board allows it to sit in a breadboard with one row open either 
side of it. This makes it more convenient for quick prototyping. 


See also: 
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SparkFun ESP32 Thing 





Connecting to the ESP32 


The ESP32 is a WiFi device and hence we will eventually connect to it using WiFi 
protocols but some bootstrapping is required first. The device doesn't know what 
network to connect to, which password to use and other necessary parameters. This of 
course assumes we are connecting as a station, if we wish the device to be an access 
point or we wish to load our own applications into it, the story gets deeper. This implies 
that there is a some way to interact with the device other than WiFi and there is ... the 
answer is UART (Serial). The ESP32 has a dedicated UART interface with pins labeled 
TX and RX. The TX pin is the ESP32 transmission (outbound from ESP32) and the RX 
pin is used to receive data (inbound into the ESP32). These pins can be connected to a 
UART partner. By far the easiest and most convenient partner for us is a USB — UART 
converter. These are discussed in detail later in the book. For now let us assume that 
we have set those up. Through the UART, we can attach a terminal emulator to send 
keystrokes and have data received from the ESP32 displayed as characters on the 
screen. Asecond purpose of the UART is to receive binary data used to "flash" the 
flash memory of the device to record new applications for execution. There are a 
variety of technical tools at our disposal to achieve that task. 


When we use a UART, we need to consider the concept of a baud rate. This is the 
speed of communication of data between the ESP32 and its partner. During boot, the 
ESP32 attempts to automatically determine the baud rate of the partner and match it. It 
assumes a default of 115200 and if you have a serial terminal attached, you will see a 
message like: 


if it is configured to receive at 115200. 


When connected to a Windows 10 machine via micro USB, it shows up as a serial 
device: 


v @ Ports (COM & LPT) 
fF Silicon Labs CP210x USB to UART Bridge (COM6) 


The default serial baud rate is 115200. 


Once the ESP32 is serially connected, we typically want to attach a monitor or terminal 
emulator against the device. The ESP-IDF framework provides a nice technique to 
achieve that. We can run the command "make monitor". This launches a monitor tool 
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that tails the ESP32 serial output. This tool is based on "miniterm" which is part of the 
"PySerial" package. We can terminate miniterm with crri+]. 


From a Linux environment, we see the serial port (usually) as /dev/ttyusBo. If we 
install the "screen" application, we can then connect a terminal using: 


$ screen /dev/ttyUSBO 115200 

To exit screen, enter "cTRL+a" followed by ": quit". 
An an alternative to screen, we also have "cu": 

$ cu -l /dev/ttyUSBO -s 115200 

To terminate the program enter "~ ." 


Another program is "minicom": 

S$ minicom --baudrate 115200 --device /dev/ttyUSBO 

And of course, since the serial port is just a stream of characters, there is nothing to 
prevent you from simply running "cat" against it: 

$ cat /dev/ttyUSBO 

If we are not sure about the settings of the serial port, we can run: 

S stty -F /dev/ttyUSBO -a 

which will return the current settings. Following a flash, you may need to change some 
setting to perform a simple cat: 

S$ stty -F /dev/ttyUSBO ispeed 115200 ospeed 115200 min 100 ixon 

See also: 


. USB to UART converters 

. Loading a program 
Screen user's manual 
PySerial — miniterm 
man(1) — stty 





Assembling circuits 

Since the ESP32 is an actual electronic component, some physical assembly is 
required. This book will not attempt to cover non-ESP32 electronics as that is a very big 
and broad subject in its own right. However, what we will do is describe some of the 
components that we have found extremely useful while building ESP32 solutions. 
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USB to UART converters 

You can't program an ESP32 without supplying it data through a UART. The easiest 
way to achieve this is through the use of a USB to UART converter. | use the devices 
that are based upon the CP2102 which can be found cheaply on eBay for under $2 
each. Another popular brand are the devices from Future Technology Devices 
International (FTDI). You will want at least two. One for programming and one for 
debugging. | suggest buying more than two just in case ... 

















When ordering, don't forget to get some male-female USB extender cables as it is 
unlikely you will be able to attach your USB devices to both a breadboard and the PC at 
the same time via direct connection and although connector cables will work, plugging 
into the breadboard is just so much easier. USB connector cables allow you to easily 
connect from the PC to the USB socket to the UART USB plug. Here is an image of the 
type of connector cable | recommend. Get them with as short a cable length as 
possible. 12-24 inches should be preferred. 








~ 


When we plug in a USB — UART into a Windows machine, we can learn the COM port 
that the new serial port appears upon by opening the Windows Device Manager. There 
are a number of ways of doing this, one way is to launch it from the DOS command 
window with: 











mmc devmgmt.msc 


Under the section called Ports (COM & LPT) you will find entries for each of the COM 
ports. The COM ports don't provide you a mapping that a particular USB socket is 
hosting a particular COM port so my poor suggestion is to pull the USB from each 
socket one by one and make a note of which COM port disappears (or appears if you 
are inserting a USB). 
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File Action View Help 
@¢9|m| 18 


b ] IEEE 1394 Bus host controllers 
> 534 Imaging devices 
» KY Intel WiUSB 
> <= Keyboards 
Mice and other pointing devices 

> 4 Monitors 
> (KY Network adapters 
4° Ports (COM & LPT) 

i ¥ Intel(R) Active Management Technology - SOL (COM3) 

- Fv Novatel Wireless VCOM GPS Port (COM4) 

v Silicon Labs CP210x USB to UART Bridge (COM11) 


Ld Standard Serial over Bluetooth link (COM13) 
> Dp Processors 

> J Security Devices 

> -g» Smart card readers 

> iy Sound, video and game controllers 

> lll System devices 

b @ Universal Serial Bus controllers 


























See also: 


. Connecting to the ESP32 
. Working with UART/serial 


Breadboards 

| find | can never have too many breadboards. | suggest getting a few full size and half 
size boards along with some 24 AWG connector wire and a good pair of wire strippers. 
Keep a trash bin close by otherwise you will find yourself knee deep in stripped 
insulation and cut wire parts before you know it. | also recommend some Dupont male- 
male pre-made wires. Ribbon cable can also be useful. 


Page 50 





Power 

We need electricity to get these devices working. | choose the MB102 breadboard 
attachable power adapters. These can be powered from an ordinary wall-wart (mains 
adapter) or from USB. It appears that the plug for wall-wart power is 2.1mm and center 
positive however | strongly suggest that you read your specific supplier's data sheets 
very carefully. There is also a potential concern that the barrel socket is wired in parallel 
with the USB input which could mean that if you attach a high voltage input (eg. 12V) 
while also having a USB source connected, you may very well damage your USB 
device. The devices have a master on/off power switch plus a jumper to set 3.3V or 5V 
outputs. You can even have one breadboard rail be 3.3V and the other 5V ... but take 
care not to apply 5V to your ESP32. By having two power rails, one at 3.3V and the 
other at 5V, you can power both the ESP32 and devices/circuits that require 5V. 





When the ESP32 starts to transmit over wireless, that can draw a lot of current which 
can cause ripples in your power supply. You may also have other sensors or devices 
connected to your supply as well. These fluctuations in the voltage can cause 
problems. It is strongly recommended that you place a 10 micro farad capacitor 
between +ve and -ve as close to your ESP32 as you can. This will provide a reservoir 
of power to even out any transient ripples. This is one of those tips that you ignore at 
your peril. Everything may work just fine without the capacitor ... until it doesn't or until 
you start getting intermittent problems and are at a loss to explain them. Let me put it 
this way, for the few cents it costs and the zero harm it does, why not? 
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Multi-meter / Logic probe / Logic Analyzer 

When your circuit doesn't work and you are staring at it wondering what is wrong, you 
will be thankful if you have a multi-meter and a logic probe. If your budget will stretch, | 
also recommend a USB based logic analyzer such as those made by Saleae. These 
allow you to monitor the signals coming into or being produced by your ESP32. Think 
of this as the best source of debugging available to you. Not only can these devices 
display signals over time, the software also allows us to specify the protocol being used 
and the content of the signal displayed at a higher level with interpretation. 


See also: 


Saleae logic analyzers 
YouTube: ESP32 and logic analyzers 








Sundry components 
You will want the usual set of suspects for sundry components including LEDs, 
resistors, capacitors and more. 


Physical construction 

When you have bread-boarded your circuit and written your application, there may 
come a time where you wish to make your solution permanent. At that point, you will 
need a soldering iron, solder and some strip-board. | also recommend some female 
header sockets so that you don't have to solder your ESP32 directly into the circuits. 
Not only does this allow you to reuse the devices (should you desire) but in the 
unfortunate event that you fry one, it will be easier to replace. 





Configuration for flashing the device 

Later on in the book you will find that when it comes time to flash the device with your 
new applications, you will have to set some of the GPIO pins to be low and then reboot. 
This is the indication that it is now ready to be flashed. Obviously, you can build a 
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circuit that you use for flashing your firmware and then place the device in its final circuit 
but you will find that during development, you will want to flash and test pretty 
frequently. This means that you will want to use jumper wires and to allow you to move 
the links of pins on your breadboards from their "flash" position to their "normal use" 
position. 
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Programming for ESP32 

The ESP32 allows you to write applications that can run natively on the device. You can 
compile applications written in the C programming language and deploy them to the 
device through a process known as flashing. In order for your applications to do 
something useful, they have to be able to interact with the environment. This could be 
making network connections or sending/receiving data from attached sensors, inputs 
and outputs. In order to make that happen, the ESP32 contains a core set of functions 
that we can loosely think of as the operating system of the device. The services of the 
operating system are exposed to be called from your application providing a contract of 
services that you can leverage. These services are fully documented. In order to 
successfully write applications for deployment, you need to be aware of the existence of 
these services. They become indispensable tools in your tool chest. For example, if 
you need to connect to a WiFi access point, there is an API for that. To get your current 
IP address, there is an API for that and to get the time since the device was started, 
there is an API for that. In fact, there are a LOT of APIs available for us to use. The 
good news is that no-one is expecting us to memorize all the details of their use. 

Rather it is sufficient to broadly know that they exist and have somewhere to go when 
you want to look up the details of how to use them. 


To sensibly manage the number and variety of these exposed APIs, we can collect sets 
of them together in meaningful groups of related functions. This gives us yet another 
and better way to manage our knowledge and learning of them. 


The primary source of knowledge on programming the ESP32 is the ESP32 SDK API 
Guide. Direct links to all the relevant documents can be found at Reference documents. 
See also: 


Espressif Systems — Manufacturers of the ESP8266 
Espressif Bulletin Board System — Place for SDKs, docs and forums 





Espressif loT Development framework 

For the ESP32, a framework has been developed by Espressif called the loT 
Development Framework which has become commonly known as "Esp-iIpF". It can be 
found on Github here: 





https://github.com/espressif/esp-idf 





The documentation for this can be found in the esp-idf/docs folder. The documentation 
is very good and should always be read thoroughly. This book should not be 
considered the primary source for this information. 
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Here is a walk through of building an environment on Linux. The full details are found in 
the doc file called "1inux-setup.rst". Our environment build will be broken down into a 
number of distinct parts. The first is the generation of the tool-chain which are the tools 
necessary to compile the programs: 


Bees 


ea -* 

mkdir esp32 

cd esp32 

sudo apt-get install git wget make libncurses-dev flex bison gperf python python- 


UW mM 


serial 
// >> Here we download and install an x86-64 build chain (compilers) 

wget https://dl.espressif.com/dl/xtensa-esp32-elf-linux64-1.22.0-61-gab8375a- 
.2.0.tar.gz 

tar -xvf xtensa-esp32-elf-linux64-1.22.0-61-gab8375a-5.2.0.tar.gz 

sudo mv xtensa-esp32-elf /opt 

export PATH=/opt/xtensa-esp32-elf/bin:SPATH 

// << End of build chain install 





S607 OO UO WD SE 





With the tools in place, what remains is the creation of the development environment 
using the ESP-IDF framework: 


git clone --recursive https://github.com/espressif/esp-idf.git 
cd esp-idf 

git submodule update --init 

export IDF_PATH=~/esp32/esp-idf 


Monin ww 


At this point, we should have all the ingredients necessary for building an application. 
The recommended way to build an application is to clone the Espressif template app 
and use that as the basis for your own work. 


cd ~/esp32 

mkdir apps 

cd apps 

git clone https://github.com/espressif/esp-idf-template.git myapp 
cd myapp 

make menuconfig 


Monn n wm 


At this point an attractive configuration menu is presented that allows us to customize 
our build environment. 


We are now ready to compile our application: 
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S make 


The targets that we can make are: 
* make menuconfig — Run the configuration menu. 
° make deconfig— 
* make all —Compile all the code. 


lash — Flash the code to the device. 


Hh 


° make 





* make clean —Clean the build removing anything that was present previously. 
* make monitor — Connect to the ESP32 serial port and display messages. 

* make erase flash — Erase the flash on the ESP32. 

¢ make app — 


° make app-flash — 





° make app-clean — 
° make bootloader — 


© make bootloader-flash — 








. make bootloader-clean — 











° make partition-table — 


It is important to note that the ESP-IDF is an evolving platform. It is being actively 
worked upon by Espressif and the community. What that means is that from time to 
time you should review how current your ESP-IDF build is and consider replacing it with 
a newer build. Realize that this may result in some rework to your applications, 
especially if build procedures or APIs change. If you are building production level 
versions, make a note of the dates of download from Guthub so that if needed, you can 
checkout those specific versions which may have worked successfully for you in the 
past. 


| recommend using "doxygen" to build an HTML document tree of the content of the IDF. 
If you don't have doxygen installed run: 


S sudo apt-get install doxygen 


Once installed, create a doxygen configuration file by running: 


S$ doxygen -g 
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The result will be a file called "Doxyfile". 


Some of the doxygen configuration changes you will want to make will include: 


° INPUT=<Root of IDF Install>/components 





° OUTPUT DIRECTORY=output 











° OPTIMIZE OUTPUT FOR C=YES 








° RECURSIVE=YES 














° GENERATE HTML=YES 























° GENERATE LATEX=NO 














° EXTRACT ALL=YES 





° EXTRACT PRIVATE=YES 











° EXTRACT PACKAGE=YES 








° EXTRACT STATIC= YES 








° EXTRACT LOCAL CLASSES =YES 























° EXTRACT LOCAL METHODS =YES 








° CLASS DIAGRAMS=NO 


° HAVE DOT=NO 





See also: 


Github: espressif/esp-idf-template 
Github: espressif/esp-idf 
ESP-IDF Getting Started Guide 











Application entry point 

When your custom ESP32 application boots within an ESP32 device, it has to start 
somewhere and that somewhere is called the "application entry point". The entry point 
into your custom ESP32 application is a function called app main with the following 
signature: 


int app main (void) 


It is your responsibility to implement this function in your C code and provide the logic 
that is performed. 
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How ESP-IDF works 
When we type "make" in an ESP-IDF template project, the Makefile is executed. It does 
us no harm in understanding how this works. 


The Makefile in our project template sets a variable called "pRogEcT Name" to the name 
of our project. It then includes the Makefile found at <1pF_PATH>/make/project.mk and 
make processing continues. 








We can run a make with verbosity switched on to see exactly what is performed: 


S$ make V 














ERBOSE=1 


The build performs the following major steps: 


* build the "cont" tool found in <IDF>/tools/kconfig 


¢ The various components are built including: 


(e) 


(e) 


(0) 


(e) 


(e) 


bt/libbt.a - Bluetooth 

driver/libdriver.a — Access for GPIO 
esp32/libesp32.a 

expat/libexpat.a — A C library for parsing XML 
freertos/libfreertos.a 

json/libjson.a — A C library for working with JSON 
log/liblog.a — Logging capabilities 

lwip/liblwip.a — Implementation of TCP/IP 
main/libmain.a 

mbed/libmbedtls.a — SSL/TLS support 
nvs_flash/libnvs_flash.a — Non Volatile storage 
spi_flash/libspi_flash.a — SPI flash driver 
tcpip_adapter/libtcpip_adapter.a — TCP/IP adapter 


¢ Build the application 


A source file compilation includes: 


¢ -std=gnu99 
e -Og 
* -ggdb 


¢ -ffunction-sections 


¢ -fdata-sections 
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The last step is the one that is likely most useful to us. At a high level it runs: 


-fstrict-volatile-bitfields 

-mlongcalls 

-nostdlib 

-MMD 

-MP 

-Wall 

-Werror 
-Wno-error=unused-function 
-Wno-error=unused-but-set-variable 
-Wno-error=unused-variable 


others 





xtensa-esp32-elf-gcec — The C compiler 
-nostdlib — Don't include the standard C library 
-L<directory> - Include a bunch of directories looking for libraries 


-u call_user start cpu0d — Specify the entry point into code 





-W1l,--gc-sections 


-Wl,-static 





-W1l,--start-group 
Link with the following libraries: 
Oo -lbt 


Oo -lbtdm_ app 





Oo -ldriver 
Oo -lesp32 
-lhal.a 


© -lcrypto 
Oo -lcore 


oO -lnet80211 





Oo -lphy 
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Oo -lrtc 


° -lpp 





Oo -lwpa 


Do whatever -T says 


° -T esp32 out.ld 


O° -T esp32.common.1d 


O° -T esp32.rom.1d 





O° -T esp32.peripherals.1d 


Link with: 
Oo -lexpat 
Oo -lfreertos 





Oo -W1,--undefined=uxTopUsedPriority 














©° -ljson 
© -llog 

Oo -llwip 
oO -Imbed 
°o /home/ 


tls 


kolban/projects/esp32/esp-idf/component 








ts/newl 


ib/] 


ib/] 


ibc.a 




















© /home/kolban/projects/esp32/esp-idf/component 
°o -lInvs_ flash 
© -lspi flash 


Oo -ltcpip_ adapter 


oO -lmain 





Oo =lgec 


Oo -W1,--end-group 





Oo -W1,-EL 








, 





ts/newl 





ib/] 





ib/] 


ibm.a 





© -o /home/kolban/projects/esp32/apps/myapp/build/app-template.elf 


Oo -W1,-Map=/home/kolban/projects/esp32/apps/myapp/build/app- 
template.map 


Error handling 

Most of the ESP32 functions we call can return an error indication in the event that 
something goes wrong. The result is an esp err _t which can be treated as an integer. 
If the function call succeeded, then the return value is EsP_ox. Any other value is an 
error indication. A macro is available called EsP_ERROR_CHECK() which takes a statement 
as a parameter. The statement is expected to return an esp err t. If the return is other 
than Esp_ok, then an assertion is raised, the ESP32 halts and the statement is written to 
the console. We must include "esp err.h" to use this capability. 























The other codes defined that are values that can be returned from ESP-IDF API calls 
include: 
































Symbol Value 
ESP_OK 0 
ESP_FAIL -1 
ESP_ERR_ NO MEM 257 (0x101) 
ESP_ERR_ INVALID ARG 258 (0x102) 
ESP_ERR_ INVALID STATE 259 (0x103) 
ESP_ERR_INVALID_ SIZE 260 (0x104) 
ESP_ERR_ NOT FOUND 261 (0x105) 
ESP_ERR_ NOT SUPPORTED 262 (0x106) 
ESP_ERR_TIMEOUT 263 (0x107) 














If you need to convert an error code into a string representation a sample code fragment 
can be found here: https://github.com/nkolban/esp32-snippets/blob/master/error 


%20handling/fragments/esp ToError.c 





See also: 


ESP-IDF logging 


The build environment menu configuration 

Within a project, we can create a configuration file that controls how the builds progress. 
This configuration file (sdkconfig) has a very attractive menu configuration tool that can 
be opened by running: 


S$ make menuconfig 
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Note: I am especially impressed with this component of the ESP-IDF. An attention to detail and quality that makes 
configuration a lot nicer to use and less error prone than hand editing files. 





After running the command we see a text based menu editor: 





kolban@kolban-VirtualBox: ~/esp32/esptest/apps/workspace/cpp 


Espressif IoT Development Framework Configuration 
Arrow keys navigate the menu. <Enter> selects submenus ---> (or empty 
submenus ----). Highlighted letters are hotkeys. Pressing <Y> 
includes, <N> excludes, <M> modularizes features. Press <Esc><Esc> to 
exit, <?> for Help, </> for Search. Legend: [*] built-in [ ] 


| SDK tool configuration --->| 
Bootloader config ---> 
Serial flasher config ---> 
Partition Table ---> 
Optimization level (Debug) ---> 
Component config ---> 


< Exit > < Help > < Save > < Load > 

















We can tab between major components and make changes. There is even selection 
context help assistance. 


Under SDK tool configuration 

* Compiler toolchain path/prefix — xtensa-esp32-elf- 

¢ Python 2 interpreter — python 
Under Bootloader config 

¢ Bootloader log verbosity — Warning 
Under Security features 

* Enable secure boot in bootloader 

¢ Enable flash encryption on boot 
Under Serial flasher config 

¢ Default serial port — /dev/ttyUSBO 

¢ Default baud rate — 115200 baud 

¢« Use compressed upload — false 

¢ Flash SPI mode — DIO 

¢ Flash SPI speed — 40MHz 
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Flash size — 2MB 


Detect flash size when flashing bootloader 


Before flashing 


After flashing 


‘make monitor’ baud rate 


Under Partition Table 


Partition Table — Single factory app, no OTA 


Under Optimization Level 


Debug or Release 


Under Component config 
Bluetooth 


ESP32-specific config 


(e) 


(e) 


(e) 


CPU frequency — 240MHz 

Reserve memory for two cores — true 

Use TRAX tracing feature — false 

Core dump destination 

System event queue size — 32 

Event loop task stack size — 2048 

Main task stack size — 4096 

Standard-out outputs adds carriage return before newline — true 
Enable 'nano' formatting options for printf/scanf family 
UART for console output 

UART console baud rate 

Enable Ultra Low Power (ULP) Coprocessor 

Panic handler behavior — Print registers and reboot 
Make exception and panic handlers JTAG/OCD aware 
Interrupt watchdog 


= Interrupt watchdog timeout (ms) 
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(e) 


(e) 


(e) 


Task watchdog 

= Invoke panic handler when Task Watchdog is triggered 
= Task watchdog timeout (seconds) 

=" Task watchdog watches CPUO idle task 

Timers used for gettimeofday function 

RTC clock source 


Extra delay in deep sleep wake stub (in us) 


Wifi 


(e) 


(e) 


(eo) 


(e) 


Initialize PHY in startup code 

Use a partition to store PHY init data 
Max TX power (dBm) 

Max number of WiFi RX buffers 


Enable Ethernet 
FreeRTOS 


(e) 


(e) 


(e) 


(e) 


Run FreeRTOS only on first core — true 


Xtensa timer to use as the FreeRTOS tick source — Timer 0 (int (1000) tick 
rate (Hz)) 


Halt when an SMP-untested function is called 

Check for stack overflow — Check by stack pointer value 

Amount of thread local storage pointers — 3 

FreeRTOS assertions — abort() on failed assertions 

Stop program on scheduler start when JTAG/OCD is detected — true 
Enable heap memory debug — false 

IS stack size 

Use FreeRTOS legacy hooks 

Debug FreeRTOS internals — ? 


Log output 


(e) 


(e) 


Default log verbosity — Warning 


Use ANSI terminal colors in log output — true 


LWIP 


(e) 


(eo) 


Enable copy between Layer2 and Layer3 packets 

Max number of open sockets — 16 

Index for thread-local-storage pointer for lwip — 0 
Enable SOQ. REUSEADDR option — false 

Enable SO_RCVBUF option 

Maximum number of NTP servers — 1 

Enable fragment outgoing IP packets 

Enable reassembly incoming fragmented IP packets 
Maximum number of retransmissions of data segments 


Maximum number of retransmissions of SYN segments 


mbedTLS 


(e) 


ie) 


(e) 


TLS maximum message content length — 16384 
Enable mbedTLS debugging — false 

Enable hardware AES acceleration 

Enable hardware MPI (bignum) acceleration 

= Use interrupt for MPI operations 

Enable hardware SHA acceleration 

Enable mbedtls time 


=» Enable mbedtls time data 


SPI Flash driver 


(e) 


Enable operation counters — false 


After changing a configuration parameter, one should perform a complete clean rebuild 
of the ESP-IDF environment. 


Adding a custom ESP-IDF component 

As you build projects, you may want to build your own custom components. To create a 
component, create a directory in the root of your application called "components" and 
within there, create a directory named after your new component. In that directory, we 
will construct our component. It should contain: 
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* component.mk 
¢ <your source files>.c 


¢ Kconfig (optional) 


Should you wish to place source files in sub-directories beneath your component 
directory, you can do so and name the additional directories in "component .mk" using the 
COMPONENT SRCDIRS variable. For example: 





COMPONENT SRCDIRS:=dirl dir2 





By default, this will compile all the C source files in the component directory and link 
them into a library for linking with your application. If you wish to name the source files 
to be compiled explicitly you can do so by naming the resulting object files using the 
COMPONENT OBJS variable. For example: 





COMPONENT OBJS := filel.o file2.o dirl/file3.o 





The Kconfig file contains details that are shown in the menu shown by "make 
menuconfig". The format of this file is a configuration language which is called 
"Kconfig". The idea is that we wish to have a set of configuration options and we wish 
to be able to set/change the value of these options. The Kconfig defines the existence 
of a set of options, their data types, their default values, the allowable values for an 
option and help text associated with an option. The "make menuconfig" then parses the 
set of distinct Kconfig files that it can find and creates a text/full-screen menu showing 
each of the options and navigation to set and change them. 


Rather than show you all the possible options that can be set as one long huge list, we 
can create menus and sub-menus of options to allow the user of the configuration to 
drill down and locate the specific options that they might want to change. 


It is described in a web file but at a high level, it has the following format: 


menu "<Menu heading text>" 
config <ITEM NAME> 

<type> 

prompt "<text>" 

default <value> 

help 

help text 

endmenu 














A specific configuration item is given aname. For example we can define: 


config OPTIONL 


This will create a new configuration option called conric_ option1. Note that the 
"CONFIG _" prefix is added to each option automatically. Each option can have a type 
associated with it. The choices of types are: 
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* bool —A true/false value specified by "y" or "n". 


* tristate —A boolean option that is either "y", "n" or not set. 


* string —A text string. 





My option3! 














* hex —Ahex number. 





My option4! 














* int —Ahn integer. 





My option5! 














Following the definition of a configuration option, we can have prompt text. For 
example: 
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config OPTION1 
bool 
prompt "This is my prompt text!" 


A default value can be supplied using the "default" option: 


config OPTION1 
bool 
prompt "This is my prompt text!" 
default y 


The prompt text is shown beside the current value of the option in the menu: 





+ ae Oe a a eh 














Help text can be provided which is shown as assistance to the user. 


config OPTION1 
bool 
prompt "This is my prompt text!" 
default y 
help 
This is my help text to select the 
correct value for OPTION1. 





This is my prompt text! 
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Detailed documentation on the ESP-IDF build system and how to configure it can be 
found in the "build_system. rst" document in Github. 


See also: 


Kconfig language 
The component.mk settings 


Creating a build environment on the Raspberry Pi 3 

Many programmers believe that Linux is a superior development environment than 
other operating systems such as Windows or Mac OSX. Words like "superior" and 
"better" are usually subjective and | will avoid any discussion along those lines. Should 
one choose to use Linux as a development environment, there are many choices for 
where one hosts it. In this section, we are going to examine using the 4 core Raspberry 
Pi model 3 as a platform for hosting Linux and building an ESP32 development 
environment. 


The CPU on the Raspberry Pi is ARM based which means that we need a cross 
compiler to build executables for an ESP32. At the time of writing, there is not a known 
location for a binary download of the tool suite for ESP32 so our choice is to build it from 
scratch. Fortunately there are instructions for this in the "linux-setup.rst" document 
found as part of the ESP-IDF project. In summary the steps are: 


S$ sudo apt-get install gawk gperf grep gettext libcurses5-dev python python-dev 
automake bison flex texinfo help2man libtool libtool-bin 





S$ git clone -b xtensa-1.22.x https://github.com/espressif/crosstool-NG.git 
cd crosstool-NG 
./bootstrap && ./configure --prefix=SPWD && make install 


./ct-ng build 


$ 

$ 

§ ./ct-ng xtensa-esp32-elf 

$ 

$ chmod -R utw builds/xtensa-esp32-elf 


Be aware that the build of the tool chain requires about 4GBytes of storage in order to 
complete. As such, you will likely need a much larger micro SD card than the minimum 
of 8GBytes that is normally used with a Pi. The resulting binaries for the tool chain end 
up at about 100MBytes. You might want to download the files pre-compiled. A version 
of the files can be downloaded from my web site from: 


http://www.neilkolban.com/esp32/downloads/xtensa-esp32-elf.tar.gz 





Once downloaded, | suggest extracting the content into /opt using: 





S$ sudo tar --extract --directory /opt --ungzip --file xtensa-esp32-elf.tar.gz 
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To physically construct a PI/ESP32 environment, | recommend the following. First, get 
two full sized breadboards and remove the power rail from one of them. Next, bind the 
two together at the edge where you removed a power rail such that there is only one 
power rail between the two boards. This will then allow an ESP32 DevKitC to bridge 
between them. Now on one of the breadboards, we can plug in a Raspberry PI 
extender. We now have both the PI and the ESP32 col-located on the boards. 


Taking a short USB cable, plug the DevKitC into the PI. This will provide both power to 
the DevKitC as well as give us a serial port. On the PI, if we now run "isusb", we will 
see the DevKitC: 


S$ lsusb 

Bus 001 Device 018: ID 10c4:ea60 Cygnal Integrated Products, Inc. CP210x UART Bridge / 
myAVR mySmartUSB light 

Bus 001 Device 003: ID 0424:ec00 Standard Microsystems Corp. SMSC9512/9514 Fast 
Ethernet Adapter 

Bus 001 Device 002: ID 0424:9514 Standard Microsystems Corp. 

Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub 








The DevkKitC is the first entry. To further validate, we can look for /dev/ttyUSBO: 


$ ls -l /dev/ttyUSBO 
crw-rw---- 1 root dialout 188, 0 Sep 25 10:27 /dev/ttyUSBO 


This is the serial port that shows up with a USB—Serial connector such as DevkKitC. 
We can now connect a serial terminal to this serial port and see the information 


produced from it. One can use a tool such as "screen" to achieve this task. This tool is 
not installed by default on the PI so we need to install it with: 


S$ sudo apt-get install screen 
Once installed, we can run: 


S screen /dev/ttyUSBO 115200 


At this point we should be seeing the serial output from the ESP32. To end our "screen" 
session, we use the cryptic: 

CTRL+A 

followed by 

rquit 

Now let us turn our attention to using the PI to control booting and other useful 


functions. We want to map some PI GPIO pins to some of the ESP32 functions. The 
choice of PI pins is arbitrary but in my solution, | used the following: 
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PI Pin ESP32 function 

17 EN 

27 100 (Used for boot mode selection) 
GND GND (common ground) 





This is illustrated in the following schematic: 


33V 
GPIO 2 (SDA) 
GPIO 3 (SCL) 


33V 
GPIO 10 (MOs}) 

GPIO 9 (MISO) 

GPIO 11 (SPICLK) GPIO 8 (CEO) 
GND GPIO 7 (CE1) 
ID_SD ID_sc 
GPIO 5 GND 
GPIO 6 GPIO 12 
GPIO 13 GND 
GPIO 19 GPIO 16 
GPIO 26 GPIO 20 
GND GPIO 21 


Raspberry Pi Header 





ESP32 DevKitC 






Now we can look to some software to achieve our goals. 


See also: 


Github: esp-idf/.../linux-setup.rst 
YouTube: ESP32 — Development environment on PI 








Compiling 

Application code for an ESP32 program is commonly written in C. Before we can 
deploy an application, we must compile the code into binary machine code instructions. 
Before that though, let us spend a few minutes thinking about the code. 


We write code using an editor and ideally an editor that understands the programming 
language in which we are working. These editors provide syntax assistance, keyword 
coloring and even contextual suggestions. After we save our entered code, we compile 
it and then deploy it and then test it. This cycle is repeated so often that we often use a 
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product that encompasses editing, compilation, execution and testing as an integrated 
whole. The generic name for such a product is an "Integrated Development 
Environment" or "IDE". There are instances of these both fee and free. In the free 
camp, my weapons of choice are Eclipse and Arduino IDE. 


The Eclipse IDE is an extremely rich and powerful environment. Originally written by 
IBM, it was open sourced many years ago. It is implemented in Java which means that 
it runs and behaves identically across all the common platforms (Windows, Linux, OSx). 
The nature of Eclipse is that it is architected as a series of extensible plug-ins. Because 
of this, many contributors across many disciplines have extended the environment and 
it is now a cohesive framework for just about everything. Included in this mix is a set of 
plug-ins which, on aggregate, are called the "C Developers Tools" or "CDT". If one 
takes a bare bones Eclipse and adds the CDT, one now has a first rate C IDE. 
However, what the CDT does not supply (and for good reason) are the actual C 
compilers and associated tools themselves. Instead, one "defines" the tools that one 
wishes to use within the CDT and the CDT takes it from there. 


For our ESP32 story, this means that if we can find (which we can) a set of C compiler 
tools that take C source and generate Xtensa binary, we can use CDT to build our 
programs. 


To make things more interesting though, we need to realize that C is not the only 
language we can use for building ESP32 applications. We can also use C++ and 
assembly. You may be surprised that | mention assembly as that is as low level as we 
can possibly get however there are odd times when we need just that (thankfully rarely) 
... especially when we realize that we are pretty much programming directly to the 
metal. The Arduino libraries (for example) have at least one assembly language file. 


For physical file types, the suffixes used for different file we will come across during 
development include: 


* .nh—C and C++ language header file 
* .c—C language source file 

* .cpp — C++ source file 

¢ .s—Assembler source file 

* .o-— Object file (compiled source) 


¢ .a—Archive library 


To perform the compilations, we need a set of development tools. 
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My personal preference is the package for Eclipse which has everything pre-built and 
ready for use. However, these tools can also be downloaded from the Internet as open 
source projects on a piece by piece basis. 


Compilation 
Let us imagine we have a "main.c" source file. How then can we properly compile that 
to get it ready for linking into an ESP32 binary? The Espressif documented mechanism 
is to use the ESP-IDF and that works great ... but there are times when we can't start 
with the Espressif make system but instead need to work in the opposite direction ... 
namely starting from an existing make system and integrating the correct steps into that 
already existent environment. What we have done is spent time studying how the ESP- 
IDF works and reverse engineered enough of it to build this recipe. First, if we run the 


ESP-IDF make system with the environment variable vz 








‘RBOS 











E Set to 1, we get a lot of 


detail. Here is what | currently see from a current build: 


xtensa-esp32-el 





function -Wno-error=unused-but-se 


f-gcc -DESP_ PLATFORM -Og -g3 -Wpointer-arith -Werror -Wno-error=unused- 


-Wno-error=unused-variable -Wall 





t-variabl 


-ffunction-sections -fdata-sections -mlongcalls -nostdlib -MMD -MP -std=gnu99 -g3 


-fstrict-volatil 
-DHAVE_CONFIG_H 


= 
HE 
aL 
=, 
=I 
<1 
= 
al 
= 
=e 
= 
= 
=i 
= 
=u 
=f 
<1 
1 
LE 
= 
= 
=1 


=1% 





/home/pi/proj 
/home/pi/proj 
/home/pi/projy 
/home/pi/projy 
/home/pi/projy 
/home/pi/proj 
/home/pi/proj 
/home/pi/projy 
/home/pi/proy 
/home/pi/proj 
/home/pi/proj 
/home/pi/proy 
/home/pi/projy 
/home/pi/proy 
/home/pi/proy 
/home/pi/projy 
/home/pi/proj 
/home/pi/proy 
/home/pi/projy 
/home/pi/projy 
/home/pi/proy 








/home/pi/proy 


e-bitfields -DMB 








EDTLS CONFIG FILE='"mbedtls/esp config.h"' 


ects/esp32/apps/parallell/main/include 


ects/esp32/esp-id 
ects/esp32/esp-id 
ects/esp32/esp-id 
ects/esp32/esp-id 
ects/esp32/esp-id 
ects/esp32/esp-id 
ects/esp32/esp-id 
ects/esp32/esp-id 
ects/esp32/esp-id 
ects/esp32/esp-id 
ects/esp32/esp-id 
ects/esp32/esp-id 
ects/esp32/esp-id 
ects/esp32/esp-id 
ects/esp32/esp-id 
ects/esp32/esp-id 
ects/esp32/esp-id 
ects/esp32/esp-id 
ects/esp32/esp-id 
ects/esp32/esp-id 


f/componen 
f/componen 
f/componen 
f/componen 
f/componen 
f/componen 
f/componen 
f/componen 
f/componen 
f/componen 
f/componen 
f/componen 
f/componen 
f/componen 
f/componen 
f/componen 
f/componen 
f/componen 





f/componen 





f/componen 


ts/bt/include 
ts/driver/include 
ts/esp32/include 
ts/expat/port/include 
ts/expat/include/expat 
ts/freertos/include 
ts/json/include 
ts/json/port/include 
ts/log/include 
ts/lwip/include/lwip 
ts/lwip/include/lwip/port 
ts/lwip/include/lwip/posix 
ts/mbedtls/port/include 
ts/mbedtls/include 
ts/newlib/include 
ts/nghttp/port/include 
ts/nghttp/include 
ts/nvs_flash/include 
ts/spi_flash/include 





ts/tcpip adapter/include 


ects/esp32/apps/parallell/build/include/ 
-c /home/pi/projects/esp32/apps/parallell/main/./main.c -o main.o 


Let us now pull it apart piece by piece and see what it going on: 


Page 73 


Page 74 


xtensa-esp-elf-gcc — This is the C compiler that generates compiled code for 
the ESP32 CPUs. 





-DESP_ PLATFORM — This sets the existence of a macro definition called 

"ESP PLATFORM’. The belief is that this can be used by the C pre-processor to 
include, exclude or otherwise manipulate the source before compilation. For 
example, there may be source files that have common code within them where 
some code is valid for one environment/platform and some other code, also 
contained in the same source file, is valid for a different environment/platform. 
The existence of ESP_PLATFORM could be used as a distinguisher within the 
code. 








-og — Optimize for debugging experience. 
-g3 — Level 3 debugging information included. 


-Wpointer-arith — Produce warnings relating to pointer arithmetic. Specifically, 
anything that relies on the size of a function type or the size of void. 


-werror — Make all warnings into errors. This stops/fails a compilation on any 
warnings produced during compile. 





Wno-error=unused-function — Don't flag an un-used function as an error. 





Wno-error=unused-but-set-variable — Don't flag an unused variable as an 
error that had a value set upon it. 








Wno-error=unused-variable — Don't flag an unused variable as an error. 
-Wal1 — Enable a large set of warnings. 
-ffunction-sections — Place each function in its own section. 
-fdata-sections — Place each piece of data in its own section. 
-mlongcalls —An Xtensa specific option 
-nostdlib — Do not use the standard startup files or libraries when linking. 
-MMD 
-mp — Something about makefiles. 
-std=gnu99 — Set the compiler standard. 
-fstrict-volatile-bitfields — How volatile bit fields should be accessed. 
-DMBEDTLS_CONFIG_FILE="mbedtls/esp_config.h" 








-DHAVE_CONFIG_H — Define a macro flag. 


* -I <various>— Specify directories which should be searched for includes. The 
majority of additional directories are included in the ESP-IDF directory structures. 


* -c—Compile to object file with no linking. 


* -o <filename>— write the output into the given file. 


If we need to include additional code that is only present on an ESP32, we can use the 
existence of the macro definition "EsP_ PLATFORM" as the indicator. For example: 





#ifdef ESP PLATFORM 
// ESP32 specific code 
#fendif 








Flashing 

Flashing is the mechanism used to move a binary from the file system into the ESP32. 
If we are using the ESP-IDF, then the process is very straightforward. We can use the 
command "make flash" and the tools needed to flash the ESP32 will be run for us with 
the correct inputs. The primary parameters for a flash are the port used to 
communicate with the ESP32 and the baud rate (transmission rate) to be used. These 
and other settings can be configured in the "make menuconfig” in the sub menu called 


"Serial flasher config": 


\(fjdev/ttyUSBO) Default serial port 


Default baud rate (921600 baud) ---> 
[*] Use compressed upload 

Flash SPI mode (DIO) ---> 

Flash SPI speed (40 MHz) ---> 

Flash size (4 MB) ---> 


We can over-ride these at the command line by using: 





S$ make flash ESPPORT=<serial port> ESPBAUD=<baud rate> 





By examination of the recipes supplied by Espressif, we find that the underlying 
command is as follows 


python /home/pi/projects/esp32/esp-idf/components/esptool py/esptool/esptool.py --chip 
esp32 --port "/dev/ttyUSB0O" --baud 230400 write flash -z --flash_mode "dio" 

--flash_ freq "40m" 

0x1000 /home/pi/projects/esp32/apps/parallell/build/bootloader/bootloader.bin 

0x10000 /home/pi/projects/esp32/apps/parallell/build/app-template.bin 

0x4000 /home/pi/projects/esp32/apps/parallell/build/partitions singleapp.bin 


Breaking this down we arrive at: 
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python — run a python script. 
esptool.py — Run the program called "esptool .py'. 
--chip esp32 — Declare that we are flashing an ESP32. 


--port "/dev/ttyusBo" — Define the serial port to which the ESP32 is 
connected. 


--baud 115200 — Define the transmission baud rate across the serial port. 
write flash — Perform the write flash command. 


-z — Unknown. 


--flash_mode "dio" — Use "dio" flash mode. 


0) 





--flash freq "40m" — Use a flash frequency of "40m" 


0x1000 bootloader.bin — Load the bootloader at 0x1000. 





0x10000 appname.bin — Load the application at 0x10000. 


0x4000 partitions singleapp.bin — Load the partition table at 0x4000. 


Following the construction of the ELF file, we now run a tool which converts the ELF into 
an uploadable image. Again, looking at the ESP-IDF tools, we find the following 
command being run: 


python /home/pi/projects/esp32/esp-idf/components/esptool py/esptool/esptool.py --chip 
esp32 elf2image --flash_mode "dio" --flash freq "40m" -o 


/home/pi/projects/esp32/apps/vl1/build/app-template.bin 
/home/pi/projects/esp32/apps/vl1/build/app-template.elf 
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python 

esptool.py 

--chip esp32 
elf2image 
--flash_mode "dio" 
--flash_freq "40m" 
-o <output file> 


<input elf file> 


Loading a program 

Once the program has been compiled, it needs to be loaded into the ESP32. This task 
is called "flashing". In order to flash the ESP32, it needs to be placed in a mode where 
it will accept the new incoming program to replace the old existing program. The way 
this is done is to reboot the ESP32 either by removing and reapplying power or by 
bringing the REST pin low and then high again. However, just rebooting the device is 
not enough. During start-up, the device examines the signal value found on cptoo. If 
the signal is low, then this is the indication that a flash programming session is about to 
happen. If the signal on crtoo is high, it will enter its normal operation mode. Because 
of this, it is recommended not to let cproo float. We don't want it to accidentally enter 
flashing mode when not desired. A pull-up resistor of 10k is perfect. 


We can build a circuit which includes a couple of buttons. One for performing a reset 
and one for bringing cpioo low. Pressing the reset button by itself will reboot the device. 
This alone is already useful. However if we are holding the "cproo low" button while we 
press reset, then we are placed in flash mode. 


This however suffers from the disadvantage that it requires us to manually press some 
buttons to load a new application. This is not a horrible situation but maybe we have 
alternatives? 


When we are flashing our ESP32s, we commonly connect them to USB->UART 
converters. These devices are able to supply UART used to program the ESP32. We 
are familiar with the pins labeled RX and TX but what about the pins labeled RTS and 
DTR ... what might those do for us? 


RTS which is "Ready to Send" is an output from the UART to inform the downstream 
device that it may now send data. This is commonly connected to the partner input CTS 
which is "Clear to Send" which indicates that it is now acceptable to send data. Both 
RTS and CTS are active low. 


DTR which is "Data Terminal Ready" is used in flow control. 


When flashing the device using the Eclipse tools and recipes the following are the flash 
commands that are run (as an example) and the messages logged: 

22:34:17 **** Build of configuration Default for project k_blinky **** 
mingw32-make.exe -f C:/Users/Userl/WorkSpace/k blinky/Makefile flash 


c:/Espressif/utils/esptool.exe -p COM11 -b 115200 write flash -ff 40m -fm qio -fs 4m 
0x00000 firmware/eagle.flash.bin 0x40000 firmware/eagle.irom0text.bin 





Connecting... 





Erasing flash... 
head: 8 ;total: 8 
erase size : 16384 


Writing at 0x00000000... (3 %) 


Page 77 


ae 


Writing at 0x00000400... (6 %) 

Writing at 0x00007000... (96 %) 

Writing at 0x00007400... (100 3%) 

Written 30720 bytes in 3.01 seconds (81.62 kbit/s)... 
Erasing flash... 
head: 16 ;total: 41 


























erase size : 102400 

Writing at 0x00040000.. (O %) 
Writing at 0x00040400.. (1 %) 
Writing at 0x00067c00... (99 %) 
Writing at 0x00068000 (100 %) 


Written 164864 bytes in 16.18 seconds (81.53 kbit/s)... 
Leaving... 


22:34:40 Build Finished (took 23s.424ms) 


As an example of what the messages look like if we fail to put the ESP32 into flash 
mode, we have the following: 


13:47:09 **** Build of configuration Default for project k_blinky **** 
mingw32-make.exe -f C:/Users/Userl/WorkSpace/k blinky/Makefile flash 
c:/Espressif/utils/esptool.exe -p COM11 -b 115200 write flash -ff 40m -fm qio -fs 4m 
0x00000 firmware/eagle.flash.bin 0x40000 firmware/eagle.irom0text.bin 

Connecting... 





Traceback (most recent call last): 
File "esptool.py", line 558, in <module> 
File "esptool.py", line 160, in connect 
Exception: Failed to connect 
C:/Users/Userl/WorkSpace/k blinky/Makefile:313: recipe for target 'flash' failed 
mingw32-make.exe: *** [flash] Error 255 








13:47:14 Build Finished (took 5s.329ms) 


The tool called esptool.py provides an excellent environment for flashing the device but 
it can also be used for "reading" what is currently stored upon it. This can be used for 
making backups of the applications contained within before re-flashing them with a new 
program. This way, you can always return to what you had before over-writing. For 
example, on Unix: 


esptool.py --port /dev/ttyUSBO read _flash 0x00000 OxFFFF backup-0x00000.bin 
esptool.py --port /dev/ttyUSBO read flash 0x10000 Ox3FFFF backup-0x10000.bin 


See also: 


. USB to UART converters 

. Error: Reference source not found 
. What is a UART? 

. esptool.py 
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Programming environments 

We can program the ESP32 using the Espressif supplied SDK on Windows using 
Eclipse. A separate chapter on setting up that environment is supplied. We also have 
the ability to program the ESP32 using the Arduino IDE. This is potentially a game 
changing story and it too been given its own important chapter. 


See also: 


Programming using Eclipse 
Programming using the Arduino IDE 


Compilation tools 

There are a number of tools that are essential when building C based ESP32 
applications. Many of these tools are supplied as part of the Xtensa tool chain. Let us 
remind ourselves that an executable that runs on the ESP32 executes machine code in 
Xtensa instruction set. This means that we need a compiler that generates Xtensa code 
as opposed to a compiler that generates Intel x86 code. 


When a compiler runs on one architecture and generates codes for a different 
architecture, that is called a cross compiler. For example, if we have a C source 
application and compile it with the Xtensa compiler on an Intel platform, we generate 
Xtensa executable code that is not executable on the Intel platform on which it was 
compiled. My convention is to install the Xtensa tool set at: 


/opt/xtensa-esp32-elf 


with the binaries themselves being in 


/opt/xtensa-esp32-elf/bin 


If we list the tools contained within we will find that they are all prefixed with "xtensa- 
esp32-elf-*". The reason for the long name is that we want to be very clear that we are 
using a cross compiler tool as opposed to a tool with the exact same name (without the 
prefix) that may already be present on the platform where we are performing the 
compilation. For example, on a Linux platform, it is not uncommon to compile a C 
program using the compiler called "gcc". If one typed "gcc main.c’", it is likely it will 
compile and produce an object file. However, the code produced would be the native 
code for the compilation platform ... likely to be Intel x86. The same program to compile 
for ESP32 would then be "xtensa-esp32-elf-gec main.c". 
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xntensa-esp32-elf-ar 
The archive tool is used to packaged together compiled object files into libraries. These 


libraries end with ". a" (archive). A library can be named when using a linker and the 
objects contained within will be used to resolve externals. 


Some of the most common flags used with this tool include: 
* -c-— Create a library 
¢ -r— Replace existing members in the library 
* -u— Update existing members in the library 

The syntax of the command is: 

ar -cru libraryName member.o member.o ... 


See also: 


GNU - ar 
xtensa-esp32-elf-nm 


esptool.py 
This tool is an open source implementation used to flash the ESP32 through a serial 


port. It is written in Python. Versions have been seen to be available as windows 
executables that appear to have been generated ". xs" files from the Python code 
suitable for running on Windows without a supporting Python runtime installation. 














* -p port |--port port — The serial port to use 


* -b baud |--baud baud — The baud rate to use for serial. Common baud rates 
include: 


© 115200 — basic speed 
© 921600 —high speed 
* -h—Help 
* {command} -h — Help for that command 
* load ram {filename} — Upload an image to RAM and execute 
* dump mem {address} {size} {filename} — Dump arbitrary memory to disk 
* read mem {address} — Read arbitrary memory location 


* write mem {address} {value} {mask} — Read-modify-write to arbitrary memory 
location 





° write flash — Write a binary blob to flash 
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© --flash freq {40m,26m, 20m, 80m} -f£ {40m,26m,20m, 80m} — SPI Flash 
frequency 

O --flash_ mode {qio,qout,dio,dout} | -fm {qio,qout,dio,dout} — SPI Flash 
mode 

O --flash_ size {4m, 2m, 8m,16m,32m,16m-cl,32m-cl,32m-c2} | -fs 


{4m, 2m, 8m, 16m, 32m, 16m-c1, 32m-c1, 32m-c2} — SPI Flash size in Mbit 
© -z Of --compress — Compress during transmission 
© {address} {fileName} —Address to write, file to write ... repeatable 
* run— Run application code in flash 


* image info {image file} — Dump headers from an application image. Here is 
an example output: 





Entry point: 40100004 
3 segments 





Segment 1: 25356 bytes at 40100000 
Segment 2: 1344 bytes at 3ffe8000 
Segment 3: 924 bytes at 3ffe8540 





Checksum: 40 (valid 


Here is an example of image_info against the bootloader.bin 
esptool.py v2.0-dev 


Image version: 1 
Entry point: 40098200 
4 segments 











Segment 1: len 0x00000 load O0x3ffc0000 file offs 0x00000018 
Segment 2: len 0x00a08 load O0x3ffc0000 file offs 0x00000020 
Segment 3: len 0x01068 load 0x40078000 file offs 0x00000a30 
Segment 4: len 0x00378 load 0x40098000 file offs 0x00001aa0 


Checksum: 92 (valid) 


* make image — Create an application image from binary files 








© --segfile SEGFILE, -f SEGFILE — Segment input file 

















© --segaddr SEGADDR, -a SEGADDR — Segment base address 











© --entrypoint ENTRYPOINT, -e ENTRYPOINT — Address of entry point 


° output 


* elf2image — Create an application image from ELF file 
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© --output OUTPUT, -o ouTPUT — Output filename prefix 








© --flash freq {40m,26m,20m,80m}, -ff {40m,26m,20m, 80m} — SPI Flash 
frequency 

Oo --flash_ mode {qio,qout,dio,dout}, -fm {qio, qout,dio,dout} — SPI Flash 
mode 

O --flash_ size {4m, 2m, 8m,16m,32m,16m-cl,32m-cl,32m-c2}, -fs 


{4m, 2m, 8m, 16m, 32m, 16m-cl, 32m-cl, 32m-c2} — SPI Flash size in Mbit 


© --entry-symbol ENTRY SYMBOL, -es ENTRY SYMBOL — Entry point symbol 
name (default 'call_user_start’) 














* read mac — Read MAC address from OTP ROM. Here is an example output: 





MAC AP: 1A-FE-34-F9-43-22 
MAC STA: 18-FE-34-F9-43-22 





* flash _id—Read SPI flash manufacturer and device ID. Here is an example 
output: 


head: 0 ;total: 0 
erase size : 0 
Manufacturer: c8 
Device: 4014 


* read flash — Read SPI flash content 
° address — Start address 
° size — Size of region to dump 
© filename — Name of binary dump 


* erase flash — Perform Chip Erase on SPI flash. This is an especially useful 
command if one ends up someone bricking the device as it should reset the 
device to its defaults. 


See also: 


. Loading a program 
. Github: themadinventor/esptool 








xtensa-esp32-elf-gcc 

The open source GNU Compiler Collection includes compilers for C and C++. If we 
look carefully at the flags that are supplied for compiling and linking code for the ESP32 
we find the following: 


Compiling 


* -c—Compile the code to a .o object file. 
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* -0os — Optimize code generation for size. 


* -02 — Optimize for performance which code result in larger code size. For 
example, instead of making a function call, code could be in-lined. 


* -ggdb — Generate debug code that can be used by the gdb debugger.. 

* -std=gnu90 — Dialect of C supported. 

¢ -wWerror — Make all warnings errors. 

* -Wno-address — Do not warn about suspicious use of memory addresses. 


* -Wpointer-arith — Warn when pointer arithmetic is attempted that depends on 


sizeof. 
* -wundef — Warn when an identifier is found in a #if directive that is not a macro. 
* -fno-inline-functions — Do not allow functions to be replaced with in-line code. 


* -mlongcallis — Translate direct assembly language calls into indirect calls. 





° mtext-section-literals — Allow literals to be intermixed with the text section. 





* -mno-serialize-volatile — Special instructions for volatile definitions. 





Linking: 
* -nostdlib — Don't use standard C or C++ system startup libraries 


See also: 


. GCC — The GNU Compiler Collection 





gen_appbin.py 
The syntax of this tool is: 


gen_appbin.py app.out boot _mode flash_mode flash_clk div flash size 


¢ flash_mode 


° 0-QIO 

° 1—QOUT 

o 2-—DIO 

o 3—DOUT 
¢ flash_clk_div 


Page 83 


° g9—80m/2 


° 1—80m/3 
o 2—80m/4 
° Oxf —80m/1 


¢ flash_size_map 
° 0-512 KB (256 KB + 256 KB) 


° 1-256 KB 

o 2—1024 KB (512 KB + 512 KB) 

o 3—2048 KB (512 KB + 512 KB) 

o 4—4096 KB (512 KB + 512 KB) 

° 5 —2048 KB (1024 KB + 1024 KB) 


° 6—4096 KB (1024 KB + 1024 KB) 
The following files are expected to exist: 
* eagle.app.v6.irom0text.bin 
* eagle.app.v6.text.bin 


° eagle.app.v6é.data.bin 





° eagle.app.v6.rodata.bin 


The output of this command is a new file called cagle.app.flash.bin. 


make 

Make is a compilation engine used to track what has to be compiled in order to build 
your target application. Make is driven by a Makefile. Although powerful and simple 
enough for simple C projects, it can get complex pretty quickly. If you find yourself 
studying Makefiles written by others, grab the excellent GNU make documentation and 
study it deeply. 


xtensa-esp32-elf-nm 
List symbols from object files. 





Useful flags: 
* --defined-only — Show only defined exports 


* --undefined-only — Show only undefined exports 
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e --line-numbers 


See also: 


xntensa-esp32-elf-ar 
GNU —- nm 


xtensa-esp32-elf-objcopy 
See also: 





GNU -— objcopy 


xtensa-esp32-elf-objdump 
Some of the more important flags are: 





* --syms — Dump the symbols in the archive. 
* --headers — Dump the section headers. 


See also: 


Wikipedia — objdump 
GNU — objdump 
man page — objdump(1) 


xxd 

This is a deceptively simple but useful tool. What it does is dump binary data contained 
within a file in a formatted form. One powerful use of it is to take a binary file and 
produce a C language data structure that represents the content of the file. This means 
that you can take binary data and include it in your applications. 


The following will read the content of inrile as binary data and produce a header file in 
the outFile. 


xxd -include <inFile> <outFile> 


Linking 

We have seen how to compile a C source file into its object file (.o) representation. 
Now we turn our attention on how to link these object files together with the ESP32 
libraries in order to produce a binary file that can be flashed into the ESP32 for 
execution. 





If we examine the output of compiling a project using the ESP-IDF with the verBosE=1 
flag set, we see the underlying command used to perform the linking. Here is an 
example and then we'll start to pull it apart: 
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xtensa-esp32-elf-gcc -nostdlib -L/home/pi/projects/esp32/esp-idf/lib 


-L/ 
-L/ 
-L/ 
-L/ 
-L/ 
-L/ 
-L/ 
-L/ 
-L/ 
-L/ 
-L/ 
-L/ 
-L/ 
-L/ 
-L/ 
-L/ 
-L/ 
-L/ 
-L/ 


home/pi/projec 
home/pi/projec 
home/pi/projec 
home/pi/projec 
home/pi/projec 
home/pi/projec 
home/pi/projec 
home/pi/projec 
home/pi/projec 
home/pi/projec 
home/pi/projec 
home/pi/projec 
home/pi/projec 
home/pi/projec 
home/pi/projec 
home/pi/projec 
home/pi/projec 
home/pi/projec 
home/pi/projec 





sections -Wl,-sta 
idf/components/bt 
id 


id 
esp32.peripherals 
llog 
id 
id 
ltcpip adapter 


-llwip 








ts/esp32/esp-idf/1l 











tic -Wl,--start-gr 
/lib -lbtdm_app 


sid -lexpat 
-lmbedtls 


f/components/newlib/lib/libm.a 


-lmain 


ts/esp32/apps/paral 
ts/esp32/apps/paral 
ts/esp32/apps/paral 
ts/esp32/apps/paral 
ts/esp32/apps/paral 
ts/esp32/apps/paral 
ts/esp32/apps/paral 
ts/esp32/apps/paral 
ts/esp32/apps/paral 
ts/esp32/apps/paral 
ts/esp32/apps/paral 
ts/esp32/apps/paral 
ts/esp32/apps/paral 
ts/esp32/apps/paral 
ts/esp32/apps/paral 
ts/esp32/apps/paral 
ts/esp32/apps/paral 
ts/esp32/apps/paral 


d 





oup 


-ldriver 


-lfreertos -W1,--undefined=uxTopUsedPriority 


lell 
lell 
lell 
lell 
lell 
lell 
lell 
lell 
lell 
lell 
lell 
lell 
lell 
lell 
lell 
lell 
lell 
lell 





/build/bootloader 

/obuild/bt 

/build/driver 

/build/esp32 

/build/esptool py 

/build/expat 

/build/freertos 

/build/json 

/build/log 

/build/lwip 

/build/mbedtls 

/build/newlib 

/build/nghttp 

/build/nvs_ flash 

/build/partition table 

/build/spi_ flash 

/build/tcpip adapter 

/build/main -u call _user start _cpu0 -Wl,--gc- 
-lbt -L/home/pi/projects/esp32/esp- 

-lesp32 /home/pi/projects/esp32/esp- 


f/components/esp32/libhal.a -L/home/pi/projects/esp32/esp-idf/components/esp32/lib 
lerypto -lcore -lnet80211 -lphy -lrtc -lpp -lwpa -L /home/pi/projects/esp32/esp- 
f/components/esp32/l1d -T esp32 out.ld -T esp32.common.ld -T esp32.rom.1d -T 


-ljson 


/home/pi/projects/esp32/esp- 

f/components/newlib/lib/libc.a /home/pi/projects/esp32/esp- 
-linghttp 
-lgcc -Wl,--end-group -W1,- 


-lnvs_ flash -lspi_ flash 


EL -o 


/hnome/pi/projects/esp32/apps/parallell/build/app-template.elf -W1l,- 


Map=/home/pi/projects/esp32/apps/parallell/build/app- 


knows how to link. 





-u call 








template.map 


xtensa-esp32-elf-gcec — The compiler for the Xtensa architecture which also 


-nostdlib — Do not link with the standard startup files and libraries. 
-L <various> — Specify the directories which should be searched for library files. 


user start cpud — Pretend that the symbol called. 


"call user start cpu0d" is undefined to force the linker to resolve it. 





-Ww 


—-Ww 








—-Ww 
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1,--ge-sections — Garbage collect unused input sections. 
1,-static — Do not link against shared libraries. 


1,--start-group — Start a group of archives. Used to resolve circular 
references. 


1,-EL — Link in little-endian format. 
<various libraries> — Link with the named libraries. 


-W1,--end-group — End a group of archives. 


* -T esp32 out.1d—Use a Linker script. Found in build/esp32.1d. 








* -T esp32.common.1d— Use a Linker script. Found in ESP_IDF/components 
/esp32/1d/esp32.common.1d. 


* -T esp32.rom.id— Use a Linker script. Found in esp 1DF/components 
/esp32/l1d/esp32.rom.1d. 











* -T esp32.peripherals.id— Use a Linker script. Found in 





ESP_IDF/components/esp32/1d/esp32.peripherals.1d. 
* -o <filename>— Write the result to the named file. 


* -W1,-Map=<filename>— Write a link map to the named file. 





Linked libraries: 
* -1bt — build/bt/libbt.a 
* -lbtdm app — ESP_IDF/components/bt/lib/libbtdm_app.a 





* -ldriver — build/driver/libdriver.a 





* -lesp32 —build/esp32/libesp32.a 

* libhal.a—ESP_IDF/components/esp32/libhal.a 

* -lcrypto — ESP_IDF/components/esp32/lib/libcrypto.a 
* -lcore — ESP_IDF/components/esp32/lib/libcore.a 

* -I1net8s0211 — ESP_IDF/components/esp32/lib/libnet80211.a 
* -lphy — ESP_IDF/components/esp32/lib/libphy.a 

* -l1rtc — ESP_IDF/components/esp32/lib/librtc.a 

* -lpp — ESP_IDF/components/esp32/lib/libpp.a 

* -lwpa — ESP_IDF/components/esp32/lib/libwpa.a 

* -lexpat — build/expat/libexpat.a 

* -1freertos — build/freertos/libfreertos.a 


* -14json — build/json/libjson.a 





* -1llog — build/log/liblog.a 








*  -llwip — build/lwip/liblwip.a 





* -l1mbedtis — build/mbedtls/libmbedtls.a 
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Within a linked executable there are a variety of "sections". We can dump those with 





lnvs_f] 








fl 





lspi_ 





-Igcc 


lmain — Project files 





lnghttp — build/nghttp/libnghttp.a 


S$ xtensa-esp32-elf --headers <file.elf> 


Here is an example (note some of the more uninteresting entries were removed 


app-template.elf: 





Sections: 
Idx Name 
O .iram0.vectors 
1 .iram0.text 
2 .dram0.bss 
3 .dram0.data 
4 .flash.rodata 
5 .flash.text 
16 .comment 
17 .xtensa.info 


From the above, here are some of the interesting parts: 


libc.a — ESP_IDF/components/newilib/lib/libc.a 


libm.a — ESP_IDF/components/newlib/lib/libm.a 


ash — build/nvs_flash/libnvs_flash.a 


ash — build/spi_flash/libspi_flash.a 


file format elf32-xtensa-le 


























































































































Size VMA LMA File off 
00000400 40080000 40080000 00006b40 
CONTENTS, ALLOC, LOAD, READONLY, CODE 
000167d2 40080400 40080400 0O00006f40 
CONTENTS, ALLOC, LOAD, READONLY, CODE 
O000£f310 3£f£fb0000 3ffb0000 00005878 
ALLOC 

000012c0 3ffbf310 3ffbf310 00005880 
CONTENTS, ALLOC, LOAD, DATA 

00005794 3£400010 3£400010 000000e0 
CONTENTS, ALLOC, LOAD, DATA 

00028ded 400d0018 400d0018 0001d714 
CONTENTS, ALLOC, LOAD, READONLY, CODE 
00000062 00000000 00000000 0020f49b 
CONTENTS, READONLY 

00000038 00000000 00000000 0020f4fd 
CONTENTS, READONLY 

































































Section Load address size 
-iram0.vectors 0x4008 0000 1024 (0x400) 
-iram0.text 0x4008 0400 91114 (0x167d2) 
-dram0.bss Ox3ffb 0000 62224 (0xf310) 
-dram0.data Ox3ffb £310 4800 (Ox12c0) 
.flash.rodata Ox3£40 0010 22420 (0x5794) 
.flash.text 0x400d 0018 167405 (0x28ded) 
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ltcpip adapter — build//tcpip_adapter/libtcpip_adapter.a 


Algn 
2**2 


ZEKQ 


ZEAS: 


2**4 


2**4 


ZED 


ZREO 


2**0 


Debugging 

When writing programs, we may find that they don't always run as expected. 
Performing debugging on an SOC can be difficult since we have no readily available 
source level debuggers. 


ESP-IDF logging 

The ESP-IDF framework provides a logging set of features. Use these as opposed to 
simple "print£()" statements. These logging items can then be inserted in your own 
application for diagnosing problems or capturing traces. 


To use the logging functions, we must include "esp _1log.h" and also include the 
generated "sdkconfig.h". 


The high level logging function is called "esp log write ()" which has the following 
signature: 
void esp log write(esp log level t level, const char *tag, const char * format, ....) 


Think of it like a specialized printf logger. The format and following parameters follow 
the printf style convention. 


By default, when logging is requested, the output is sent to the primary serial stream. 
However, we can over-ride that destination by using the function called 

esp log set vprintf(). This takes as a parameter a reference to a C function that has 
the same syntax as vprintf. Specifically: 


int myPrintFunction(const char *format, va_list arg) 


When we wish to log a message, we choose a log level to write to. The log levels 
available are: 


° ESP LOG NONE 











° ESP LOG ERROR 








* ESP LOG WARN 





* ESP_LOG INFO 


° ESP LOG DEBUG 




















° ESP LOG VERBOSE 








The logged output is of the format: 


Page 89 


<log level> (<time stamp>) <tag>: <message> 


Where log level is one of "=", "w", "r=", "Dp" or "v". The time stamp is the number of 
milliseconds since boot. 





We also have a global setting which is the maximum log level we should log. For 
example if we set ESP_Loc warn then messages at level ESP_LOG WARN, ESP_LOG ERROR 
will be logged but ESP LOG INFO, ESP LOG DEBUG and ESP LOG VERBOSE Will be excluded. 









































The tag parameter to the logging function provides an indication of which logical 
component/module issues the message. This provides context to what otherwise might 
be ambiguous messages. 


C language macros are provided to make using the logging simpler. The macros are: 









































* ESP LOGE(tag, format, ..) - Log an error. 

* ESP LOGW(tag, format, ..) - Log a warning. 

* ESP LOGI(tag, format, ..) - Log information. 

* ESP LOGD(tag, format, ..) - Log debug. 

* ESP LOGV(tag, format, ..) - Log verbose information. 


Since logging is included or excluded at compile time, we can specify the logging level 
to include in our builds. At compile time, this may exclude certain log statements from 
the source. The compilation flag -pLoc_ LocaL_ LeveL controls the logging levels 
included. 














For the log statements that remain in the code after compilation that were not excluded 
at build time, we can control the log level at run-time by calling esp log level set(). 
The signature of this function is: 


void esp log level set(const char *tag, esp log level t level) 


The tag names the logging groups that we will show. If the special tag of name "*" is 
supplied, this matches all tags. 


If we are writing interrupt handling routines, do not use these logging functions within 
those. 


There are a couple of global configuration settings relating to log output that can be set 
within the "menuconfig’. These are: 


* Default log verbosity — choice - CONFIG_LOG_DEFAULT_LEVEL 
¢ Use ANSI terminal colors in log output — boolean - CONFIG_LOG_ COLORS 
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See also: 


Error handling 
esp_log_level_set 
esp_log_set_vprintf 
esp_log_write 


Exception handling 

At run-time, things may not always work as expected and an exception can be thrown. 
For example, you might attempt to access storage at an invalid location or write to read 
only memory or perform a divide by zero. 


When an exception is detected on an ESP32, a register dump is performed on the 
primary serial output. For example the text may look like: 





























Guru Meditation Error of type LoadProhibited occured on core 0. Exception was un- 
handled. 

Register dump: 

PC : 400£835d PS : 00060a30 AO : 800f83e9 Al > 3ffc45a0 
A2 : 3f4084bc A3 : 3ffc4738 A4 : 00000001 A5 : 00000000 
A6 : 3ffb013c AT : 00000001 A8 > df405982 AQ > 3ffc4550 
Al10 : ffffffff All : 3ffc4738 Al2 : 000000ba Al13 : 0000002b 
Al4 : 0000001b A15 : 00000001 SAR : 00000020 EXCCAUSE: 0000001c 
EXCVADDR: df405986 LBEG : 4000c28c LEND > 4000c296 LCOUNT : 00000000 
Rebooting... 


If we know the location of the exception, we can analyze the executable (app. out) to 
figure out what piece of code caused the problem. 


xtensa-esp32-elf-objdump -x app-template.elf -d 
Another option is to load the binary with GDB as in: 
xtensa-esp32-elf-gdb ./build/app-template.elf 
From there we can run: 


info symbol 0x<address> 


This will return an indication of where within the code an error was detected. Here is an 
example: 


(gdb) info symbol 0x400f8806 
initSockets + 114 in section .flash.text 


This showed that an exception occurred within my "initSockets" function (which was 
indeed the case). 


If we then run: 


list *Ox<address> 


it will show us the source line number and lines. Here is another example: 
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(gdb) list *0x400f8806 
0x400f8806 is in initSockets 
(/home/pi/projects/esp32/apps/myapp/main/./app main.c:54). 








49 

50 struct sockaddr _in clientAddress; 

51 socklen t clientAddressLength = sizeof (clientAddress) ; 
52 int clientSock = accept(sock, (struct sockaddr *) &clientAddress, 
é&clientAddressLength) ; 

53 checkSocketRC(clientSock, "accept"); 

54 printf ("Accepted a client connection\n") ; 

55 } 

56 

57 static void dumpState() { 

58 esp err t err; 


Core dump processing 

When a computer program runs, there is always "state" associated with that program. 
At a minimum, there is the current location at which the program is executing (this is 
called the "program counter"). In addition, there are the values of variables currently in 
effect as well as the stack which contains information about the nested functions that 
may have been called to arrive at the current program location. Taken in aggregate, all 
this information can be extremely useful to you should your program fail or crash 
unexpectedly. This set of information is sometimes called a memory dump or a system 
dump and in Unix terms it is called a "core dump". ESP32 architecture has decided to 
use the term "core dump". 


When an ESP32 application fails, we can configure that application to generate a core 
dump that can subsequently used for analysis. By default, the generation of a core 
dump is disabled. We can change the setting within "make menuconfig" under the 
settings: 





Component config > ESP32-specific config > Core dump destination 








ESP32-specific config 
Arrow keys navigate the menu. <Enter> selects submenus ---> (or empty submeni 
----). Highlighted letters are hotkeys. Pressing <Y> includes, <N> excludes 
<M> modularizes features. Press <Esc><Esc> to exit, <?> for Help, </> for 
Search. Legend: [*] built-in [ ] excluded <M> module < > module capable 


CPU frequency (240 MHz) ---> 


[*] Reserve memory for two cores 
Use TRAX tracing feature 
ore dump destination (None --->| 


(32) System event queue size 
(2048) Event loop task stack size 
(4096) Main task stack size 
[*] Standard-out output adds carriage return before newline 
[ ] Enable 'nano' formatting options for printf/scanf family 

UART for console output (Default: UARTO, TX=GPIO1, RX=GPIO3) ---> 
(115200) UART console baud rate 

















If we select that option, we will find it has three possible settings: 


* Flash — The core dump data will be written to flash memory. 
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* uart — The core dump data will be encoded and written to the serial (UART) 
output stream. 


* None — No core dump information will be saved or written. 








Core dump destination 7 
Use the arrow keys to navigate this window or press the 
hotkey of the item you wish to select followed by the <SPACE 
BAR>. Press <?> for additional information about this 





Flash 


6,4 a 


< Help > 




















If we change the core dump destination to UART, an additional pair of options appear: 





Core dump destination (UART ---> 
iG) Core dump print to UART delay (NEW) 
(1) Core dump module logging level 
(32) System event queue size 
(2048) Event loop task stack size 








These are: 


* Core dump print to UART delay —Atime specified in milliseconds to pause 
before the core dump data is written to the console. This can be interrupted by a 
keystroke (assuming a terminal is attached). The default is 0 which means dump 
immediately. 


* Core dump module logging level — This is a value between 0 (no output) and 5 
(most verbose). It seems that this effects the debug output of the core dump 
generator as opposed to the content of the core dump itself. 





There is a relationship between the core dump setting and what the ESP32 should do 
as a whole when there is a problem. The options for the ESP32 are found in 





Component config — ESP32-specific config — Panic handler behavior 
The options for that setting are: 

¢ Print registers and halt 

¢ Print registers and reboot 

¢ Silent reboot 

¢ Invoke GDBStub 
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For use with the core dump, | recommend "print registers and halt". 





Panic handler behaviour 
Use the arrow keys to navigate this window or press the 
hotkey of the item you wish to select followed by the <SPACE 
BAR>. Press <?> for additional information about thi 


rint registers and halt 
( ) Print registers and reboot 
( ) Silent reboot 

() 


Invoke GDBStubff 


< Help > 

















Once setup, when a fatal exception occurs, the following is an example of output: 








Guru Meditation Error of type StoreProhibited occurred on core 0. Exception was 
unhandled. 
Register dump: 
































PC : 0x400e6c23 PS : 0x00060330 AO : Ox800d0b41 Al : Ox3ffb83b0 
A2 : 0x00000000 A3 : Ox00000000 A4 : 0x00060023 A5 : Ox3ffb6c54 
A6 : 0x00000000 AT : 0x00000001 A8 : Ox0000007b A9Y : Ox3ffb8390 
Al10 : 0x000001f6 All : Ox3ffblbfO A12 : Ox3f4052a8 Al13 : Ox0000001f 
Al4 : 0x00000001 A15 : 0x00000005 SAR : 0x0000001b EXCCAUSE: 0x0000001d 
EXCVADDR: 0x00000000 LBEG : 0x00000000 LEND : 0x00000000 LCOUNT : 0x00000000 
Backtrace: 0x400e6c23:0x3ffb83b0 0x400d0b41:0x3ffb83d0 


























CORE DUMP START 
kA8AAAYAAABkAQAA 
VGz7P/CC+z90hPs/ 
cIP7P/CD+z/2AQAASD37P0g9+z 9UbPs /QD37PxgAAAAAAAAAY ogwEVRs+z8AAAAA 
AQAAAFRO+z9tYWLuAIgwIiJISgAAAAAAAAAAAFCE+ z 8AAAAAT AMGAAEAAAAAAAAA 
AAAAAAAAAAAAAAAAAFT 7 P2hU+z/QOVPs / AAAAAAAAAAABAAAAAAAAAThCQD8BAAAAA 














AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA== 
CORE DUMP END 























CPU halted. 


Once we have captured core dump data, the next step is to examine it to determine 
what it means. By and large it is a blob of binary data that by itself is not meaningful to 
us. Fortunately the ESP-IDF provides a tool to help us analyze it. That tool is called 


"W "W 
espcoredump.py . 


The primary input is a text file that contains the core dump output. This is the text 
between the "core pump sTarT" and "coRE DUMP END" tags. This data is encoded in 
base 64. Once the file has been written (in the following examine into a file called 
core.dat), we can run the formatting command: 
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python SIDF_PATH/components/espcoredump/espcoredump.py info _corefile -t b64 -c 





core.dat build/app-template.elf 


Here is an example of the output of that tool: 











CI 
Nn 

















P32 CORE DUMP STA 








CURRENT THREAD REGIST 


RT 





ERS 























0x400e6c17 <app_main+47> 











pc 0x400e6c17 
lbeg 0x0 O 
lend 0x0 O 
lcount 0x0 0 
sar 0x0 0 
ps 0x60330 394032 
threadptr <unavailable> 
br <unavailable> 
scomparel <unavailable> 
acclo <unavailable> 
acchi <unavailable> 
mO <unavailable> 
m1 <unavailable> 
m2 <unavailable> 
m3 <unavailable> 
expstate <unavailable> 
fe4r lo <unavailable> 
fe4r hi <unavailable> 
f64s <unavailable> 
Lor <unavailable> 
fsr <unavailable> 
ad Ox3ffb83b0 1073447856 
al 0x0 0 
a2 0x0 0 
a3 0x60023 393251 
a4 0x0 0 
a5 0x0 0 
aé 0x0 0 
al 0x0 0 
a8 0x0 0 
aQ 0x0 0 
al0 0x0 0 
all 0x0 0 
al2 0x0 0 
al3 0x0 0 
al4 0x0 0 
al5 0x0 0 

CURRENT THR 
#0 Ox400e6c17 in app main () at 
/home/kolban/esp32/esptes 











Id Target Id 


THREADS INFO 
Frame 





EAD STACK 




















t/apps/workspace/test_ core dump/main/./main.c:29 
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6 process 5 Ox40082ae7 in xQueueGenericReceive (xQueue=0x0, pvBuffer=0x0, 
xTicksToWait=<unavailable>, xJustPeeking=0) at /home/kolban/esp32/esptest/esp- 
idf/components/freertos/./queue.c:1594 

5 process 4 Ox40082ae7 in xQueueGenericReceive (xQueue=0xl, pvBuffer=0xl1, 
xTicksToWait=<unavailable>, xJustPeeking=0) at /home/kolban/esp32/esptest/esp- 
idf/components/freertos/./queue.c:1594 

4 process 3 0x40084716 in prvProcessTimerOrBlockTask 
(xNextExpireTime=<optimized out>, xListWasEmpty=<optimized out>) at 
/nome/kolban/esp32/esptest/esp-idf/components/freertos/./timers.c:487 

3 process 2 0x400d1l3ac in esp vApplicationIdleHook () at 
/home/kolban/esp32/esptest/esp-idf/components/esp32/./freertos hooks.c:52 

2 process 1 0x400d1l3ac in esp vApplicationIdleHook () at 
/home/kolban/esp32/esptest/esp-idf/components/esp32/./freertos hooks.c:52 
* 1 <main task> O0x400e6c17 in app _ main () at 
/home/kolban/esp32/esptest/apps/workspace/test core dump/main/./main.c:29 

ALL MEMORY REGIONS 

Name Address Size Attrs 
.ctc.text 0x400c0000 0x0 RW 
-iram0.vectors 0x40080000 0x400 R XA 
-iram0.text 0x40080400 0x13280 R XA 
.dram0.data O0x3ffb0000 0x2434 RWA 
.flash.rodata 0x3f400010 0x64b0 RWA 
.flash.text 0x400d0018 0x18380 R XA 
.coredump.tasks Ox3ffb6c54 0x164 RW 
.coredump.tasks Ox3ffb82f0 0x160 RW 
.coredump.tasks Ox3ffb8b10 0x164 RW 
.coredump.tasks Ox3ffb89a0 0x164 RW 
.coredump.tasks Ox3ffb845c 0x164 RW 
.coredump.tasks Ox3ffb7190 Oxl6c RW 
.coredump.tasks Ox3ffb92b8 0x164 RW 
.coredump.tasks Ox3ffb91c0O Oxec RW 
.coredump.tasks Ox3ffb631lc 0x164 RW 
.coredump.tasks Ox3ffb6230 OxeO RW 
.coredump.tasks Ox3ffb5cl14 0x164 RW 
.coredump.tasks Ox3ffb5b20 Oxe8 RW 

ESP32 CORE DUMP END 



































At first glance, it looks like it contains a bewildering amount of data ... too much to make 


sense of, however, | hope you will take 


the time to learn how to interpret it as there is 


much to see. Lets start at the top section called: 





CURRENT THR 





EAD R 








EGISTE 





RS 








These are the CPU registers in effect when the exception happened. Personally, there 
is little there that | can interpret with one important exception which is "pc". This is the 
"Program Counter" which is the address of the instruction that was being executed 


when the exception was encountered. 


Next comes the section called: 


CURRENT THREAD STACK 
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An address by itself though isn't that useful. 


This is where things get interesting. This contains the call stack of the current thread ... 
the one that contained the exception. Here we will see the path of nested calls that took 
us to our failure. The final element in the list is exactly where the failure was 
encountered. For example: 


#0 Ox400e6c17 in app main () at 
/home/kolban/esp32/esptest/apps/workspace/test_ core dump/main/./main.c:29 


But this time ... notice that the source file and exact line number within the source is 
displayed. We can't get much more precise than this. | believe that this is the most 
important information that we can gleam from the examination of the core. 

Next we find a section called: 


THREADS INFO 





This contains a record for each "thread" or FreeRTOS task running in the ESP32. This 
can provide a context on what else may have been running. 


Finally we have a section called: 





ALL MEMORY REGIONS 











This lists all the memory sections within the environment. Good to see where things are 
mapped and useful to see if we might be treading on storage we don't own. 


See also: 


ESP-IDF documentation on core dump processing 
Wikipedia — core dump 








Using a debugger (GDB) 

GDB is the GNU Debugger and is an excellent tool for debugging compiled C source 
code. Although it is primarily designed to debug OS hosted applications such as those 
compiled for Windows or Linux it can be used to debug code on the ESP32. 


First we must change a configuration setting in our compilation process for our ESP32 
application using "make menuconfig". Visit the menu setting: 


Component config — FreeRTOS — Panic handler behavior 


From there, select "Invoke GDBStub"! 
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kolban@kolban-VirtualBox: ~/esp32/esptest/apps/workspace/aptest 


Panic handler behaviour 
Use the arrow keys to navigate this window or press the 
hotkey of the item you wish to select followed by the <SPACE 
BAR>. Press <?> for additional information about this 


( ) Print registers and halt 

( ) Print registers and reboot 
Silent reboot 

Go iravoke cosstud 


< Help > 














Now rebuild and re-deploy your solution. Now the next time a crash/exception happens 
in your ESP32 application, you will enter a GDB state where you can run xtensa-esp32- 
elf-gdb on your PC and use a serial connection to interact with the ESP32. For 
example: 


xtensa-esp32-elf-gdb ./build/app-template.elf -b 115200 -ex 'target remote 
/dev/ttyUSBO' 


You will now be in a gdb session where you can execute the normal gdb commands you 
would use for debugging. 


OpenOCD and JTAG 
We must install the Espressif distributed version of OpenOCD. Perform the following: 


sudo apt get install libusb-1.0 


. git clone --recursive https://github.com/espressif/openocd-esp32.git 
cd openocd-esp32 


1 

2 

3 

4. ./bootstrap 
5. ./configure 
6 


222? 


For my testing | bought an FTDI based C232HM-DDHSL-O. These run about $40 on 
eBay. The pin codings are: 
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Function Id Wire color 
VCC 1 Red 
TCK — Test Interface 2 Orange 
Clock 

TDI — Test Data Input 3 Yellow 
TDO — Test Data Output | 4 Green 
TMS — Test Mode Select |5 Brown 
GPIOLO 6 Grey 
GPIOL1 7 Purple 
GPIOL2 8 White 
GPIOL3 9 Blue 
GND 10 Black 














Given the four signals needed for JTAG (TCK, TDI, TDO and TMS), these can be found 
mapped to the following ESP32 pins: 
































JTAG function |GPIO Wire color 
TCK GPIO 13 Orange 
TDI GPIO 12 Yellow 
TDO GPIO 15 Green 
TMS GPIO 14 Brown 
See also: 


Open On-Chip Debugger — OpenOCD 





OpenOCD docs — PDF 





Github: espressif/openocd-esp32 





FTDI €232HM Data Sheet 





Dumping IP Addresses 
Being a WiFi and TCP/IP device, you would imagine that the ESP32 works a lot with IP 
addresses and you would be right. We can generate a string representation of an IP 


address using: 


printf(IPSTR, IP2STR(pIpAddrVar) ) 


the IPSTR macro is "3d.%d.%da.%a" so the above is equivalent to: 


printf ("Sd.%d.%d.%d", 


IP2STR(pIpAddrVar) ) 
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which may be more useful in certain situations. The IP2STR macro takes a 32bit 
integer (an IP address) and produces 4 bytes worth of parameters corresponding to the 
4 bytes of an IP address. 


See also: 


IP2STR 


Debugging and testing TCP and UDP connections 

When working with TCP/IP, you will likely want to have some applications that you can 
use to send and receive data so that you can be sure the ESP32 is working. There are 
a number of excellent tools and utilities available and these vary by platform and 
function. 


Android - Socket Protocol 
The Socket Protocol is a free Android app available from the Google play app store. 
See: 





https://play.google.com/store/apps/details?id=aprisco.app.android 





Android - UDP Sender/Receiver 

The UDP Sender/Receiver is another free Android app available from the Google play 
app store. What makes this one interesting is its ability to be a UDP (as opposed to 
TCP) sender and receiver. See: 


https://play.google.com/store/apps/details?id=com.jca.udpsendreceive 





Windows - Hercules 

Hercules is an older app for Windows that still seems to work just fine on the latest 
releases. It looks a little old in the tooth now but still seems to get the job done just fine. 
See also: 


http:/Awww.hw-group.com/products/hercules/index_en.html 





SocketTest 
This is a Java app that also works well on Windows. Again, an old app but works 
exactly as advertized. Nothing fancy. 


See also: 


http://sockettest.sourceforge.net/ 
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Linux - netcat (nc) 
Netcat can send and receive arbitrary data over TCP/UDP. 





For example, to listen on UDP and dump the incoming data: 
$ nce -u -l -p 9999 | od -x 
To listen on a TCP port and dump the incoming data: 


$ nce -l1 -p 9999 -k | od -x 


See also: 
man(1) — nc 
man(1) — od 

Curl 


Curl is powerful and comprehensive command line tool for performing any and all URL 
related commands. It can transmit HTTP requests of all different formats and receive 
their responses. It has a bewildering set of parameters available to it which is both a 
blessing and curse. You can be pretty sure that if it can be done, Curl can do it ... 
however be prepared to wade through a lot of documentation. 


Here are some simple recipes for some of the more common curl commands: 


Issue a get against a target: 
S$ curl http://hostname 
Send data in an HTTP post: 


S$ curl http://hostname --data "data to send" 


Include an additional header: 


S$ curl http://hostname --header "name: value" 





Redirect the output to a file 


S$ curl http://hostname --output <filename> 


See also: 
. Making a REST request using Curl 
* Curl 
Curl C API 


curl_east_setopt 
libcurl examples 
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Eclipse - TCP/MON 
One of the most powerful and useful tools available is called TCP/IP Monitor that is 


supplied as part of Eclipse and distributed with the "Eclipse Web Developer Tools". 
The TCP/IP monitor is opened through the Eclipse view called "TCP/IP Monitor". 








a 
a 
4 


TCA 


4 & Debug 
© TCP/IP Monitor 

















ore 

















If you can't find it in the view finder, the chances are high that you haven't installed 
"Eclipse Web Developer Tools". Once launched, open its properties pane: 





















[TCP/IP Monitor TCP/IP Monitor 


Configure TCP/IP monitors on local and remote ports. 


4 








Show the TCP/IP Monitor view when there is activity 


TCP/IP Monitors: 





Status Host name Type Local... Auto-st... Add... 
Edit... 


Remove 


Start 
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From there you can add local listeners. These will be TCP/IP listeners that listen on a 
local port where Eclipse is running. During configuration, you specify another IP 
address and port number. When TCP traffic now arrives at the listener on which TCP/IP 
Monitor is watching, it will forward that traffic to the partner while at the same time 
logging it to the TCP/IP Monitor screen. 





SS New Monitor 


Local monitoring port: 9999 = 


Monitor 








Host name: 192.168.1.17| 
Port: 80 = 
Type: HTTP ~ 





Timeout (in milliseconds): 0 —_ 


Start monitor automatically 


SS Gow 

















For example, here TCP/IP Monitor is listening on 192.168.1.2 (localhost) which is where 
Eclipse is running. It is listening on port 9999. When TCP/IP traffic arrives at that 
address, it will be sent onwards to 192.168.1.17 (which happens to be my ESP32 
device) to port 80. 


Here is an example of log | saw when sending a browser request: 
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#2 Probl... | TCP/L.. & 4) Tasks GCons.. [i Prop.. =gProg.. + Search @Term.. & History ©) Error... (2) Inter... 











Ome yv 
4 § localhost:9999 Time of request: 8:11.49.998 PM 

‘ll /goodbye Response Time: 1259 ms 

fal /favicon.ico Type: HTTP 
Request viewer type: | Byte AA Response viewer type: 
Request: Response: 
Size: Size: 
Header: GET /goodbye HTTP/1.1 Header: HTTP/1.0 200 OK 
Encoding: <None> v Encoding: <None> v 


<html><body><b>Please</b> come back again soo * 











As you can see, the information captured here is powerful stuff. We can see each traffic 
request, its content and HTTP headers. 


httpbin.org 
When testing HTTP protocols, connecting to the web site at http://httpbin.org can be 
invaluable. It provides a host of services for testing HTTP requests. 





RequestBin 
Another excellent HTTP testing resource. We can send a request to a URL and then 
see exactly what was received by the target. The URL for this service is 


http://requestb.in/. 


tcpdump 

This Linux based tool can capture and report on IP traffic into and out of your PC. 
Where this might be useful for our ESP32 work is that if we direct traffic from the ESP32 
to a Linux app, we can look at the low level protocol. 


ESP-IDF component debugging 
Some of the components of the ESP-IDF have their own debugging techniques and 
have special instructions for enablement. 
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LWIP 

In lwipopts.h Change the #define for Lwrp pEBUc to LwIP_DBc oN. This is the master 
debug flag. However there are sub components that then declare what to debug. 
These include: 


- DNS DEBUG 


To enable these, edit the component .mk for LWIP and add criacs with these variables 
set to LWIP_DBG ON. 














Run a Blinky 

Physically looking at an ESP32 there isn't much to see that tells you all is working well 
within it. There is a power light and a network transmission active light ... but that's 
about it. A technique that | recommend is to always have your device execute a 
"blinking led" which is commonly known as a "Blinky". This can be achieved by 
connecting a GPIO pin to a current limiting resistor and then to an LED. When the 
GPIO signal goes high, the LED lights. When the GPIO signal goes low, the LED 
becomes dark. If we define a timer callback that is called (for example) once a second 
and toggles the GPIO pin signal value each invocation, we will have a simple blinking 
LED. You will be surprised how good a feeling it will give simply knowing that 
something is alive within the device each time you see it blink. 


The cost of running the timer and changing the I/O value to achieve a blinking should 
not be a problem during development time so | wouldn't worry about side effects of 
doing this. Obviously for a published application, you may not desire this and can 
simply remove it. 


However, although this is a trivial circuit, it has a lot of uses during development. First, 
you will always know that the device is operating. If the LED is blinking, you know the 
device has power and logic processing control. If the light stops blinking, you will know 
that something has locked up or you have entered an infinite loop. 


Another useful purpose for including the Blinky is to validate that you have entered flash 
mode when programming the device. If we understand that the device can boot up in 
normal or flash mode and we boot it up in flash mode, then the Blinky will stop 
executing. This can be useful if you are using buttons or jumpers to toggle the boot 
mode as it will provide evidence that you are not in normal mode. On occasion | have 
mis-pressed some control buttons and was quickly able to realize that something was 
wrong before even attempting to flash it as the Blinky was still going. 
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WiFi subsystem 


WiFi Theory 

When working with a WiFi oriented device, it is important that we have at least some 
understanding of the concepts related to WiFi. At a high level, WiFi is the ability to 
participate in TCP/IP connections over a wireless communication link. WiFi is 
specifically the set of protocols described in the IEEE 802.11 Wireless LAN architecture. 


Within this story, a device called a Wireless Access Point (access point or AP) acts as 
the hub of all communications. Typically it is connected to (or acts as) as TCP/IP router 
to the rest of the TCP/IP network. For example, in your home, you are likely to have a 
WiFi access point connected to your modem (cable or DSL). WiFi connections are then 
formed to the access point (through devices called stations) and TCP/IP traffic flows 
through the access point to the Internet. 


Fry 1 


irnlipe 1] 
Of Se Petal 





The devices that connect to the access points are called "stations": 
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; 
hee {— _\ 


Point 
Station 


An ESP32 device can play the role of an Access Point, a Station or both at the same 
time. 


Very commonly, the access point also has a network connection to the Internet and acts 
as a bridge between the wireless network and the broader TCP/IP network that is the 
Internet. 


A collection of stations that wish to communicate with each other is termed a Basic 
Service Set (BSS). The common configuration is what is known as an Infrastructure 
BSS. In this mode, all communications inbound and outbound from an individual station 
are routed through the access point. 


A station must associate itself with an access point in order to participate in the story. A 
station may only be associated with a single access point at any one time. 


Each participant in the network has a unique identifier called the MAC address. This is 
a 48bit value. 


When we have multiple access points within wireless range, the station needs to know 
with which one to connect. Each access point has a network identifier called the BSSID 
(or more commonly just SSID). SSID is service set identifier. It is a 32 character value 
that represents the target of packets of information sent over the network. 


See also: 


Wikipedia — Wireless access point 
Wikipedia — IEEE 802.11 
Wikipedia — WiFi Protected Access 
Wikipedia — IEEE 802.11i-2004 








Initializing the WiFi environment 
WiFi is only a part of the capabilities of an ESP32. As such, there may be some times 
when you actually don't want to use the WiFi subsystem. To accommodate those 
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patterns, the initialization of the WiFi subsystem is expected to be performed by you 
when you write your applications. This is done by calling the esp wifi init () method. 
The recommended way of doing this is as follows: 


wifi init config _t config = WIFI_INIT CONFIG DEFAULT (); 
esp wifi _init(&config); 





See also: 


esp_wifi_init 


Setting the operation mode 

The ESP32 can either be a station in the network, an access point for other devices or 
both. Remember, when an ESP22 is being a station, it can connect to a remote access 
point (your WiFi hub) while when being an access point, other WiFi stations can connect 
to the ESP32 (think of the ESP32 as becoming a WiFi hub). This is a fundamental 
consideration and we will want to choose how the device behaves early on in our 
application design. Once we have chosen what we want, we set a global mode 
property which indicates which of the operational modes our device will perform (station, 
access point or station AND access point). 


This choice is set with a call to esp wifi set mode(). The parameter is an instance of 
wifi _mode_t which can have a value of WIFI MODE NULL, WIFI MODE STA, WIFI MODE AP 
Or WIFI MopbE apsta. Wecan call esp wifi get _mode() to retrieve our current mode 
state. 














Scanning for access points 

If the ESP32 is going to be performing the role of a station we will need to connect to an 
access point. We can request a list of the available access points against which we can 
attempt to connect. We do this using the esp wifi scan start () function. 


The results of a WiFi scan are stored internally in ESP32 dynamically allocated storage. 
The data is returned to us when we call esp wifi scan get ap records() which also 
releases the internally allocated storage. As such, this should be considered a 
destructive read. 





Ascan record is contained in an instance of a wifi_ap_ record_t structure that contains: 
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uints8 t bssid[6] 
uint8 t ssid[32] 
uint8 t primary 


wifi second chan _t second 





int8 t rssi 





wifi_auth_mode_t authmode 


The wifi auth mode t is one of: 


* WIFI AUTH OPEN — No security. 





I 


* WIFI AUTH weP — WEP security. 
* WIFI AUTH WPA PSK — WPA security. 


* WIFI AUTH WPA2 PSK —WPA2 security. 

















* WIFI AUTH WPA WPA2 PSK — WPA or WPA2 security. 





After issuing the request to start performing a scan, we will be informed that the scan 
completed when a sYSTEM EVENT SCAN DONE event is published. The event data 
contains the number of access points found but that can also be retrieved with a call to 


esp wifi scan get ap num(). 


























Should we wish to cancel the scanning before it completes on its own, we can call 


esp wifi scan _stop(). 


Here is a complete sample application illustrating performing a WiFi scan. Much of the 
work is performed in the event handler. When we detect a scan completion event, we 
retrieve the located access points and log their details. 


#include "esp wifi.h" 
#include "esp system.h" 
#include "esp event.h" 
#include "esp event _loop.h" 
#include "nvs_flash.h" 





esp_err t event_handler(void *ctx, system_event_t *event) 


{ 




















if (event->event_id == SYSTEM EVENT SCAN DONE) { 
printf ("Number of access points found: d\n", 
event->event_info.scan_done.number) ; 





uintl6 t apCount = event->event_info.scan_done.number; 
if (apCount == 0) { 
return ESP OK; 
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wifi_ap_ record t *list = 

(wifi_ap_record_t *)malloc(sizeof(wifi_ap_record_t) * apCount); 
ESP_ERROR_ CHECK (esp wifi_scan_get_ap records(&apCount, list)); 
int i; 

















for (i=0; i<apCount; i++) { 
char *authmode; 















































switch(list[i].authmode) { 

case WIFI_AUTH OPEN: 
authmode = "WIFI AUTH OPEN"; 
break; 

case WIFI AUTH WEP: 
authmode = "WIFI AUTH WEP"; 
break; 

case WIFI_AUTH WPA PSK: 
authmode = "WIFI AUTH WPA PSK"; 
break; 

case WIFI_AUTH WPA2_ PSK: 
authmode = "WIFI AUTH WPA2 PSK"; 
break; 

case WIFI AUTH WPA WPA2 PSK: 
authmode = "WIFI AUTH WPA WPA2 PSK"; 
break; 

default: 
authmode = "Unknown"; 
break; 





} 
printf ("ssid=%s, rssi=%d, authmode=%s\n", 
list[i].ssid, list[i].rssi, authmode) ; 
} 
free(list); 
} 
return ESP OK; 





int app _main (void) 
{ 

nvs_flash_init(); 
tcpip adapter init(); 
ESP_ERROR CHECK (esp event loop init(event handler, NULL) ); 
wifi init config t cfg = WIFI INIT CONFIG DEFAULT () ; 
ESP_ERROR_ CHECK (esp wifi _init(&cfg)); 
ESP_ERROR_ CHECK (esp wifi _set_ storage (WIFI STORAGE RAM) ); 
ESP_ERROR_CHECK (esp wifi set _mode(WIFI MODE STA)); 
ESP_ERROR_CHECK(esp_wifi_start()); 






































// Let us test a WiFi scan 
wifi _scan_config t scanConf = { 
.-ssid = NULL, 
.bssid = NULL, 
.channel = 0, 
.Sshow_hidden = 1 





Hw 
ns 
tu 











/ ERROR_CHECK (esp wifi scan_start(&scanConf, 0)); 
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return 0; 


} 


Using the Arduino libraries we can also make network scans. Here is an example: 


int8 t count 


= WiFi.scanNetworks(); 


printf ("Found %d networks\n", count) ; 


for (uint8_ 


t i=O; i<count; i++) { 


String ssid; 
uint8 t encryptionType; 


int32 t 


RSSI; 


uint8 t *BSSID; 
int32_t channel; 





WiFi.getNetworkInfo(i, ssid, encryptionType, RSSI, BSSID, 
printf ("ssid=%s\n", ssid.c_str()); 

} 

See also: 


Handling WiFi events 
esp_wifi_scan_start 


esp_wifi_scan_stop 
esp_wifi_scan_get_ap_records 
esp_wifi_scan_get_ap_num 


Handling WiFi events 
During the course of operating as a WiFi device, certain events may occur that ESP32 
needs to know about. These may be of importance or interest to the applications 
running within it. Since we don't know when, or even if, any events will happen, we 
can't have our application block waiting for them to occur. Instead what we should do is 
define a callback function that will be invoked should an event actually occur. The 
function called esp event loop init() does just that. It registers a function that will be 
called when the ESP32 detects certain types of WiFi related events. The registered 
function is invoked and passed a rich data structure that includes the type of event and 
associated data corresponding to that event. The types of events that cause the 


callback to 





occur are: 


¢ We connected to an access point 


¢ We disconnected from an access point 


« The 


authorization mode changed 


channel); 


¢ Astation connected to us when we are in Access Point mode 


¢ Astation disconnected from us when we are in Access Point mode 


¢ ASSID scan completes 
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When the ESP32 WiFi environment operates, it publishes "events" when something at 
the WiFi level occurs such as a new station connecting. We can register a callback 
function that is invoked when an event is published. The signature of the callback 
function is: 
esp_err t eventHandler(void *ctx, system_event_t *event) { 

// Handle event here ... 


return ESP OK; 
} 








Typically, we need to also include the following: 
¢ #include <esp_event.h> 
¢ #include <esp_event_loop.h> 
¢ #include <esp_wifi.h> 
¢ #include <esp_err.h> 


To register the callback function, we invoke: 


esp event loop init (eventHandler, NULL); 


If we wish to subsequently change the event handler associated with our WiFi handling 
we can call: 


esp event loop set cbh(eventHandler, NULL); 





When the event handler is invoked, the event parameter is populated with details of the 
event. The data type of this parameter is a "system _event_t" which contains: 
system_event_id_t event_id 


system _event_info t event_info 





We should include "esp event .h" to gain access to these functions and definitions. Let 
us now look at the two properties passed to the event handler in the system_event_t 
data structure. These properties are "event id" and "event info". Ata high level, the 
event _id describes what kind of event was detected while event_info contains the 
specific details of the event based on the type identified in event _id. 


* event _id—An enumeration type with the following potential values: 





© SYSTEM EVENT WIFI READY — ESP32 WiFi is ready. 

















© SYSTEM EVENT SCAN DONE — Finished scanning for access points. The 
scan_done data field is valid to be accessed. 


























© SYSTEM EVENT STA start — Started being a station. 
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© SYSTEM EVENT STA stop — Stopped being a station. 


























© SYSTEM EVENT STA CONNECTED — Connected to an access point as a station. 





The connected data field is 























valid to be accessed. 


© SYSTEM EVENT STA DISCONNECTED — Disconnected from access point while 


being a station. The disconnected data field is valid to be accessed. 





O° SYSTEM EVENT STA AUTHMODE CHANGE 
The auth change data 
































© SYSTEM EVENT STA GO7 




















— Authentication mode has changed. 


field is valid to be accessed. 


r_ 1p — Got an assigned IP address from the access 


point that we connected to while being a station. The got_ip data field is 


valid to be accessed. 






































© SYSTEM EVENT AP START — Started being an access point. 
© SYSTEM EVENT AP stop — Stopped being an access point. 
© SYSTEM EVENT AP STACONNECTED —A Station connected to us while we are 











being an access point. The s 






































ta_connected data field is valid to be accessed. 


© SYSTEM EVENT AP STADISCONNECTED —A Station disconnected from us while we 
are being an access point. The sta_ disconnected data field is valid to be 





accessed. 














© SYSTEM EVENT AP PROBEREQRECVED — Received a probe request while we are 
being an access point. The ap probereqrecved data field is valid to be 














accessed. 

















* event info -— This is a C language union of distinct data types that are keyed off 
the event id. The different structures contained within are: 





Structure 


Field 


Event 





system_event_sta_connected_t 


connected 


SYSTEM _ EVENT STA CONNECTED 





system_event_sta_disconnected_t 


disconnected 


SYSTEM EVENT STA DISCONNECTED 





system_event_sta_scan_done_t 





scan_done 


SYSTEM EVENT SCAN DONE 





system_event_sta_authmode_change t 


auth_change 


SYSTEM _ EVENT STA_AUTHMODE CHANGE 





system_event_sta_got ip t 


got_ip 


SYSTEM _ EVENT STA _GOT_IP 








system_event_ap_staconnected_t 


sta_connected 


SYSTEM EVENT AP STACONNECTED 





system_event_ao_stadisconnected_t 


sta_disconnected 


SYSTEM _ EVENT AP STADISCONNECTED 








system_event_ap probe_req_rx t 








ap_probereqrecved 














SYSTEM EVENT AP PROBEREQRECVED 
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These data structures contain information pertinent to the event type received. 


system_event_sta_connected_t 


This data type is associated with the syst 


uint8 t ssid[32] 
uint8 t ssid len 


uint8 t bssid[6] 





uint8 t channel 





wifi_auth_mode_ t authmode 








EM 














EVENT STA CONNECT event. 


The ssid is the WiFi network name to which we connected. The ssid_len is the 
number of bytes in the ssid field that contain the name. The bssid is the MAC address 
of the access point. The channel is the wireless channel used for the connection. The 
authmode is the security authentication mode used during the connection. 


system_event_sta_disconnected_t 


This data type is associated with the syst 


uint8 t ssid[32] 


uint8 t ssid_len 


uint8 t bssid[6] 


uint8 t reason 








EM 





EVENT STA _DISCONN 














ECT 


ED event. 








The reason code is an indication of why we disconnected. Symbolics are defined for 
each of the numeric reason codes to allow us to write more elegant and comprehensible 
applications should we need to consider a reason code:.: 
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IED—1 








WIFI REASON UNSPECIE 





WIFI REASON AUTH EXP 





IRE —2 




















WIFI REASON AUTH LEAVE —3 








WIFI REASON ASSOC EXPIRE —4 





WIFI REASON ASSOC_TO 





WIFI REASON NOT AUTH 





WIFI REASON NOT ASSO 














omMaNy — 5 


ED—-—6 








CED—7 











EAVE — 8 





WIFI REASON ASSOC_L 


° WIFI _R 
° WIFI_R 
° WIFI_R 
*) WLBT UR: 
° WIFI_R 
° WIFI_R 
° WIFI_R 
° WIFI R 
° WIFI_R 
° WIFI_R 
° WIFI R 
° WIFI_R 
° WIFI_R 
° WIFI_R 
° WIFI_R 


° WIFI_R 


EASON ASSOC _NOT AUTHED —9 





EASON DISASSOC_PWRCA 


EASON IE INVALID—13 








EASON MIC FAILURE — 14 
























































EASON AKMP INVALID — 20 

















r 


























EASON BEACON TIMEOUT — 200 








° WIFI_R 
° WIFI_R 


° WIFI_R 





EASON NO AP FOUND — 201 
EASON AUTH FAIL — 202 


EASON ASSOC_FAIL — 203 











& WIP T UR 














system_event_sta_scan_done_t 


This data type is associated with the system 


P BAD — 10 


EASON DISASSOC_SUPCHAN BAD — 11 


EASON IE IN 4WAY DIFFERS —17 


EASON_GROUP_CIPHER INVALID — 18 


EASON INVALID RSN IE CAP—22 


EASON 802 1X AUTH FAILED—23 


EASON HANDSHAKE TIMEOUT — 204 


EASON 4WAY HANDSHAKE TIMEOUT — 15 


EASON _GROUP_KEY UPDATE TIMEOUT — 16 


EASON PAIRWISE CIPHER INVALID —19 


EASON UNSUPP_RSN IE VERSION — 21 


EASON CIPHER SUITE REJECTED — 24 











EV. 





INT SCAN DONI 








uint32 t status 


uint8 t number 


uint8 t scan_id 


See also: 





z event. 
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Scanning for access points 
esp_wifi_scan_get_ap_records 


system_event_authmode_change_t 























This data type is associated with the sysTEM EVENT STA _AUTHMODE_ CHANGE event. 


wifi auth mode t old mode 





wifi auth mode t new mode 





system_event_sta_got_ip_t 





This data type is associated with the sysTEM EVENT STA GOT Ip event. 

















tcpip adapter ip info t ip info 





The ip_info element is an instance of a tcpip adapter ip info t which contains three 
fields: 


* ip-The IP address. 
* netmask — The network mask. 
* gw— The gateway for communications. 


All three of these fields are of ip4 addr _t which is a 32bit representation of an IP 
address. During development, you might want to consider logging the IP address of the 
device. You can do this using: 


ESP_LOGD(tag, "Got an IP: " IPSTR, IP2STR(&event->event_info.got_ip.ip _info.ip)); 





system_event_ap_staconnected_t 





























This data type is associated with the sysTEM EVENT AP STACONNECTED event. 


uint8 t mac[6] 


uint8 t aid 


system_event_ap_stadisconnected_t 








This data type is associated with the sySTEM EVENT AP STADISCCONNECTED event. 























uint8 t mac[6] 


uint8 t aid 


system_event_ap_probe_req_rx_t 
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This data type is associated with the sysTEM EVENT AP PROBREQRECVED event. 


int rssi 


uint8 t mac[6] 


If we enable the correct logging levels, we can see the events arrive and their content. 
For example: 


























D (2168) event: SYSTEM EVENT STA CONNECTED, ssid:RASPI3, ssid_len:6, 
bssid:00:00:13:80:3d:bd, channel:6, authmode:3 

V (2168) event: enter default callback 
V (2174) event: exit default callback 














and 





D (9036) event: SYSTEM EVENT STA GOTIP, 1ip:192.168.5.62, mask:255.255.255.0, 
gw:192.168.5.1 

V (9036) event: enter default callback 

I (9037) event: ip: 192.168.5.62, mask: 255.255.255.0, gw: 192.168.5.1 

V (9043) event: exit default callback 




















Station configuration 

When we think of an ESP32 as a WiFi Station, we will realize that at any one time, it 
can only be connected to one access point. Putting it another way, there is no meaning 
in saying that the device is connected to two or more access points at the same time. 


The identity of the access point to which we wish to be associated is set within a data 
structure called wifi_sta_config t. 


The wi fi_sta_config t contains: 


char ssid[32] 

char password[64] 

bool bssid_ set 
uint8 t bssid[6] 


Contained within that structure are two very important fields called "ssia" and 
"password". The ssid field is the SSID of the access point to which we will connect. 
The password field is the clear text value of the password that will be used to 
authenticate our device to the target access point to allow connection. 


An example initialization for this structure might be: 


wifi config t staConfig = { 
-sta = { 
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.ssid="<access point name>", 
-password="<password>", 
-bssid_set=false 


}; 

Once we have populated an instance of this structure, we can instruct ESP32 about its 
content using: 

esp wifi_set_config(WIFI_IF STA, (wifi_config t *) &staConfig) ; 

We should previously have called esp wifi_set_mode(). with either: 


esp_wifi_set_mode (WIFI MODE STA) 





or 


esp wifi_set_mode(WIFI_ MODE APSTA) 





See also: 


esp_wifi_set_mode 
esp_wifi_set_config 


Starting up the WiFi environment 

Since WiFi has states that it must go through, a question that may be asked is "When is 
WiFi ready to be used?". If we imagine that an ESP32 boots from cold, the chances are 
that we want to tell it to be either a station or an access point and then configure it with 
parameters such as which access point to connect to (if it is a station) or what its own 
access point identity should be (if it is going to be an access point). Given that these 
are a sequence of steps, we actually don't want the ESP32 to execute on these tasks 
until after we have performed all our setup. For example, if we boot an ESP32 and ask 
it to be an access point, if it started being an access point immediately then it may not 
yet know the details of the access point it should be or, worse, may transiently appear 
as the wrong access point. As such, there is final command that we must learn which is 
the instruction to the WiFi subsystem to start working. That command is 

esp wifi start (). Prior to calling that, all we are doing is setting up the environment. 
Only by calling esp wifi start () does the WiFi subsystem start doing any real work on 
our behalf. If our mode is that of an access point, calling this function will start us being 
an access point. If our mode is that of a station, now we are allowed to subsequently 
connect as a station. There is a corresponding command called esp wifi _stop() which 
stops the WiFi subsystem. 


See also: 


esp_wifi_start 
esp_wifi_stop 
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Connecting to an access point 

Once the ESP32 has been set up with the station configuration details which includes 
the SSID and password, we are ready to perform a connection to the target access 
point. The function esp wifi connect () will form the connection. Realize that this is 
not instantaneous and you should not assume that immediately following this command 
you are connected. Nothing in the ESP32 blocks and as such neither does the call to 
this function. Some time later, we will actually be connected. We will see two callback 
events fired. The first is sysTEM EVENT STA CONNECTED indicating that we have 
connected to the access point. The second event is sySTEM EVENT STA GoT_ Ip which 
indicates that we have been assigned an IP address by the DHCP server. Only at that 
point can we truly participate in communications. If we are using static IP addresses for 
our device, then we will only see the connected event. 















































Should we disconnect from an access point, we will see a 
SYSTEM EVENT STA DISCONNECTED event. To disconnect from a previously connected 
access point we issue the esp wifi disconnect () Call. 





























There is one further consideration associated with connecting to access points and that 
is the idea of automatic connection. There is a boolean flag that is stored in flash that 
indicates whether or not the ESP32 should attempt to automatically connect to the last 
used access point. If set to true, then after the device is started and without you having 
to code any API calls, it will attempt to connect to the last used access point. This is a 
convenience that | prefer to switch off. Usually, | want control in my device to determine 
when | connect. We can enable or disable the auto connect feature by making a call to 


esp wifi set auto connect (). 





Here is a complete sample illustrating all the steps needed to connect to an access 
point and be informed when we are ready to being work: 


include "freertos/FreeRTOS.h" 
include "esp wifi.h" 

include "esp system.h" 
include "esp event.h" 

include "esp event loop.h" 
include "nvs_flash.h" 

include "tcpip_adapter.h" 








esp_err t event_handler(void *ctx, system_event_t *event) 


{ 











if (event->event id == SYSTEM EVENT STA GOT IP) { 
printf("Our IP address is " IPSTR "\n", 
IP2STR(&event->event_info.got_ip.ip info.ip)); 




















printf("We have now connected to a station and can do things...\n") 
} 
return ESP_OK; 
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} 


int app_main (void) 
{ 

nvs_flash_init(); 
tcpip adapter init(); 
ESP ERROR _CHECK( esp event loop init(event_ handler, NULL) ); 
wifi init config t cfg = WIFI_INIT CONFIG DEFAULT (); 
ESP_ERROR_ CHECK(esp wifi _init(&cfg) ); 
ESP ERROR _CHECK( esp wifi set storage (WIFI STORAGE RAM) ); 
ESP ERROR _CHECK( esp wifi set _mode(WIFI MODE STA)); 
wifi config t sta config = { 












































.sta = { 
-ssid = "RASPI3", 
-password = "password", 


-bssid_set = 0 


he 

ESP ERROR CHECK (esp wifi set _config(WIFI_IF STA, &sta_config)); 
ESP ERROR _CHECK(esp wifi start()); 

ESP ERROR CHECK (esp wifi connect ()); 





























return 0; 


When we connect to an access point, our device is being a station. The connection to 
the access point doesn't automatically mean that we now have an IP address. We still 
have to request an allocated IP address from the DHCP server. This can take a few 
seconds. In some cases, we can get away with the device requesting a specific IP 
address. This results in a much faster connection time. If we do specify data, we also 
need to supply DNS information should we need to connect to DNS servers for name 
resolution. 


Here is a fragment of logic that allocates us a specific IP address: 


#include <lwip/sockets.h> 


// The IP address that we want our device to have. 
#define DEVICE IP "192.168.1.99" 








// The Gateway address where we wish to send packets. 
// This will commonly be our access point. 
define DEVICE GW "P92. 0 685.1501" 








// The netmask specification. 
define DEVICE NETMASK "2594 200420000" 











// The identity of the access point to which we wish to connect. 
define AP TARGET SSID "RASPI3" 


// The password we need to supply to the access point for authorization. 
define AP_ TARGET PASSWORD "password" 
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esp err t wifiEventHandler(void *ctx, system_event_t *event) 


{ 





return ESP OK; 





} 





// Code fragment her 
nvs_ flash _init(); 
tcpip_ adapter init(); 


tcpip adapter dhcpc_stop(TCPIP_ ADAPTER IF STA); // Don't run a DHCP client 
tcpip_ adapter ip info_t ipInfo; 











inet _pton(AF INET, DEVICE IP, &ipInfo.ip); 


inet _pton(AF INET, DEVICE GW, &ipInfo.gw) ; 
inet _pton(AF INET, DEVICE NETMASK, &ipInfo.netmask) ; 


tcpip adapter set _ip info(TCPIP ADAPTER IF STA, &ipInfo); 












































ESP ERROR_CHECK (esp event loop init (wifiEventHandler, NULL)); 
wifi init config t cfg = WIFI INIT CONFIG DEFAULT () ; 

ESP ERROR _CHECK(esp wifi init(&cfg) ); 
ESP ERROR CHECK (esp wifi set storage (WIFI STORAGE RAM) ); 


ESP ERROR_CHECK (esp wifi set _mode (WIFI MODE STA)); 



























































wifi config t sta config = { 
.sta = { 
.ssid = AP TARGET SSID, 
-password = AP_TARGET PASSWORD, 


-bssid_set = 0 
} 
hi 
ESP ERROR CHECK (esp wifi set _config(WIFI_IF STA, &sta_config)); 
ESP ERROR CHECK (esp wifi _start()); 
ESP ERROR_CHECK (esp wifi _connect()); 





























See also: 


. Handling WiFi events 
esp_wifi_connect 
esp_wifi_disconnect 


Being an access point 

So far we have only considered the ESP32 as a WiFi station to an existing access point 
but it also has the ability to be an access point to other WiFi devices (stations) including 
other ESP32s. 


In order to be an access point, we need to define the SSID that that allows other 
devices to distinguish our network. This SSID can be flagged as hidden if we don't wish 
it to be found in a scan. In addition, we will also have to supply the authentication mode 
that will be used when a station wishes to connects with us. This is used to allow 
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authorized stations and dis 


allow non-authorized ones. Only stations that know our 


password will be allowed to connect. If we are using authentication, then we will also 
have to choose a password that the connecting stations will have to know and supply to 


successfully connect. 


The first task in being an access point is to flag the ESP32 as such using the 
esp wifi set _mode() function and pass in the flag that requests we be either a 
dedicated access point or an access point and a station. This will be either: 





esp wifi _set_mode (WIFI MOD 


or 





esp wifi _set_mode(WIFI_MOD 


E AP); 


E APSTA) ; 


Next we need to supply the configuration information. We do this by populating an 
instance of wifi _ap config t. The wifi_ap_config t contains: 


* ssid —The WiFi ssid name upon which we will listen for connecting stations. 


* ssid _len— The length in bytes of the ssid if not NULL terminated. 


* password — The password used for station authentication. 


* channel — The channel we will use for networking. 


* authmode — How we 
° open 
o wep 
o wpa 
° wpa2 


° wpa_wpa2 


wish stations to authenticate (if at all). The choices are 


* ssid hidden — Should we broadcast our ssid. 


* max connection — The number of concurrent stations. The default and maximum 


is 4. 


° beacon interval — Unknown. 100. 


An example of initialization 


wifi config _t apConfig = { 
-ap = { 
.ssid="<access point 
.ssid_len=0, 


of this structure might be: 


name>", 


.password="<password>", 


.channel=0, 
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.authmode=WIFI AUTH OPEN, 
.ssid_hidden=0, 
-max connection=4, 





.beacon_interval=100 


}; 

With the structure populated, we call esp wifi set _config() ... for example: 

esp wifi_set_config(WIFI_IF AP, &apConfig); 

Finally, we call esp wifi start (). 

Here is a snippet of code that can be used to setup and ESP32 as an access point: 


When we become an access point, an ESP32 WiFi event is produced of type 
SYSTEM EVENT AP sTaRT. Note that there is no payload data associated with this event. 

















Once the ESP32 starts listening for station connects by being an access point, we are 
going to want to validate that this works. You can use any device or system to scan and 
connect. Personally, | use a Raspberry PI 3 for testing as it provides a nice Linux 
environment and has a WiFi adapter build in. You can also choose to plug in a separate 
WiFi dongle into one of the extra USB ports. One of the first tools we want to run is 
called "iwlist" which will perform a scan for us: 


S$ sudo iwlist wlanl scan 


In the results, we can look for our ESP32 ... for example: 


Cell 02 - Address: 18:FE:34:6A:94:EF 
ESSID:"ESP32" 

Protocol: IEEE 802.11bgn 

ode:Master 

Frequency:2.412 GHz (Channel 1) 
Encryption key:off 

Bit Rates:150 Mb/s 

Quality=100/100 Signal level=100/100 



































One of the other tools available on that environment is called "wpa_c1i" which provides 
a wealth of options for testing WiFi. The recipe | use is to connect to an access point 
from the command line is: 

$ sudo wpa cli 

add_network 


set_network <num> ssid "<SSID>" 
set network <num> key mgmt NONE 





enable network <num> 
status 


You may have to run 


select network <num> 
reconnect 
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or 


reasociate 


to connect to the target and you can run 


disconnect 

to disconnect from the access point. 
ifname — show current interface 

interface <name> - select current interface 


To perform a scan run the command "scan". When complete, run "scan results" to see 
the list. 








When a station connects, the ESP32 will raise the system EVENT AP STACONNECTED 


event. When a station disconnects, we will see the sySTEM EVENT AP DISCONNECTED 
event. 


















































See also: 
man(8) — wpa_cli 


When a remote station connects to the ESP32 as an access point, we will see a debug 
message written to UART1 that may look similar to: 


station: £0:25:b7:ff:12:c5 join, AID = 1 

This contains the MAC address of the new station joining the network. When the station 
disconnects, we will see a corresponding debug log message that may be: 

station: £0:25:b7:ff£:12:c5 leave, AID = 1 

From within the ESP32, we can determine how many stations are currently connected 
with a call to wifi _softap get station num(). If we wish to find the details of those 
stations, we can call wifi softap get station info() which will return a linked list of 


wifi sta list _t. We have to explicitly release the storage allocated by this call with an 
invocation Of wifi_softap free station info(). 


Here is an example of a snippet of code that lists the details of the connected stations: 


uint8 stationCount = wifi _softap_get_station_num(); 


os printf ("stationCount = %d\n", stationCount) ; 
wifi sta_list_t *stationInfo = wifi_softap_get_station_info(); 
if (stationInfo != NULL) { 

while (stationInfo != NULL) { 


os printf ("Station IP: %d.%d.%d.%d\n", IP2STR(&(stationInfo->ip) )); 
stationInfo = STAILQ NEXT(stationInfo, next); 








} 


wifi _softap free station _info(); 
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When an ESP32 acts as an access point, this allows other devices to connect to it and 
form a WiFi connection. However, it appears that two devices connected to the same 
ESP32 acting as an access point can not directly communicate between each other. 
For example, imagine two devices connecting to an ESP32 as an access point. They 
may be allocated the IP addresses 192.168.4.2 and 192.168.4.3. We might imagine 
that 192.168.4.2 could ping 192.168.4.3 and visa versa but that is not allowed. It 
appears that they only direct network connection permitted is between the newly 
connected stations and the access point (the ESP32) itself. 


This seems to limit the applicability of the ESP32 as an access point. The primary 
intent of the ESP32 as an access point is to allow mobile devices (eg. your phone) to 
connect to the ESP32 and have a conversation with an application that runs upon it. 


See also: 


esp_wifi_set_config 
esp_wifi_set_mode 


Working with connected stations 

When our ESP32 is being an access point, we are saying that we wish to allow stations 
to connect to it. This brings in the story of managing those stations. Common things 
we might want to do are: 


¢ Determine when a new station connects 

¢ Determine when a previously connected station leaves 
¢ List the currently connected stations 

¢ Disconnect one or more currently connected stations 


We can register an event handler for detecting new station connects and existing station 
disconnects. The event handler will receive systEM EVENT AP STACONNECTED when a 
station connects and sySTEM EVENT AP STADISCONNECTED what a station leaves. 
























































We can get the list of currently connected stations using the 

esp wifi get station list() function. This returns a linked list of stations. The 
storage for this list is allocated for us and we should indicate that we are no longer in 
need of it by calling esp wifi free station list () when done. 


If for some reason the logic in our environment wants to forcibly disconnect a currently 
connected station, we can use the esp wifi kick station() Call. 


See also: 
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Handling WiFi events 
esp_wifi_free_station_list 
esp_wifi_get_station_list 
esp_wifi_kick_station 


WiFi at boot time 

The ESP32 can store WiFi start-up information in flash memory. This allows it to 
perform its functions at start-up without having to ask the user for any special or 
additional information. This capability is controlled by a function called 

esp wifi _set auto connect () and its partner called esp wifi get auto connect (). 
The values of the settings used for an auto connect are those that are saved in flash 
memory. These are the values set when we call esp wifi _set_config() but only if we 
have instructed the ESP32 to record those settings to flash. This is itself controlled by a 
Call to esp wifi set storage(). 





See also: 


esp_wifi_set_auto_connect 
esp_wifi_get_auto_connect 
esp_wifi_set_storage 


The DHCP client 

When the ESP32 connects to an access point as a station, it also runs a DHCP client to 
connect to the DHCP server that it assumes is also available at the access point. From 
there, the station is supplied its IP address, gateway address and netmask. There are 
times however when we want to supply our own values for this data. We can do this by 
calling tcpip adapter set ip info() during setup. The recipe is as follows: 

tcpip adapter init(); 

tcpip_ adapter dhcpc_stop(); 

tcpip_ adapter set ip info(); 

esp wifi _init(); 

esp wifi _set_mode(); 


esp wifi _set_config(); 
esp wifi_start(); 





esp wifi _config(); 


(Note that the parameters are omitted in the above). 


The setup for calling tcpip adapter set ip info () canbe as follows: 


tcpip_ adapter ip info _t ipInfo; 

IP4 ADDR(&ipInfo.ip, 192,168,1,99); 

IP4 ADDR(&ipInfo.gw, 192,168,1,1); 

IP4 ADDR(&ipInfo.netmask, 255,255,255,0); 

tcpip_ adapter set _ip info(TCPIP ADAPTER IF STA, &ipInfo); 





Alternative, using strings we have: 
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tcpip_ adapter ip info _t ipInfo; 


inet _pton(AF INET, "192.168.1.99", &ipInfo.ip); 
inet _pton(AF INET, "192.168.1.1", &ipInfo.gw); 
inet _pton(AF_ INET, "255.255.255.0", &ipInfo.netmask) ; 








tcpip adapter set _ip info(TCPIP ADAPTER IF STA, &ipInfo); 





See also: 


tcpip_adapter_set_ip_info 
tcpip_adapter_dhcpc_start 
tcpip_adapter_dhcpc_stop 
tcpip_adapter_dhcpc_get_status 
tcpip_adapter_dhcpc_option 
inet_pton 


The DHCP server 

When the ESP32 is performing the role of an access point, it is likely that you will want it 
to also behave as a DHCP server so that connecting stations will be able to be 
automatically assigned IP addresses and learn their subnet masks and gateways. 


The DHCP server can be started and stopped within the device using the APIs called 
wifi softap dhcps_start() and wifi_softap dhcps_stop(). The current status 
(started or stopped) of the DHCP server can be found with a call to 

wifi _softap dhcps status(). 


The default range of IP addresses offered by the DHCP server is 192.168.4.1 upwards. 
The first address becomes assigned to the ESP8266 itself. It is important to realize that 
this address range is not the same address range as your LAN where you may be 
working. The ESP8266 has formed its own network address space and even though 
they may appear with the same sorts of numbers (192.168.x.x) they are isolated and 
independent networks. If you start an access point on the ESP8266 and connect to it 
from your phone, don't be surprised when you try and ping it from your Internet 
connected PC and don't get a response. 


See also: 


Error: Reference source not found 


Current IP Address, netmask and gateway 

Should we need it, we can query the environment for the current IP address, netmask 
and gateway. The values of these are commonly set for us by a DHCP server when we 
connect to an access point. The function called tcpip adapter get ip info() returns 
our current value. Since the ESP32 can have two IP interfaces (one for an access point 
and one for a station), we supply which interface we wish to retrieve. 
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When we connect to an access point and have chosen to use DHCP, when we are 
allocated an IP address, an event is generated that can be used as an indication that 
we now have a valid IP address. 


See also: 


Handling WiFi events 
Error: Reference source not found 
tcpip_adapter_get_ip_info 


WiFi Protected Setup - WPS 

The ESP8266 supports WiFi Protected Setup in station mode. This means that if the 
access point supports it, the ESP8266 can connect to the access point without 
presenting a password. Currently only the "push button mode" of connection is 
implemented. Using this mechanism, a physical button is pressed on the access point 
and, for a period of two minutes, any station in range can join the network using the 
WPS protocols. An example of use would be the access point WPS button being 
pressed and then the ESP8266 device calling wifi_wps enable() and then 

wifi _wps start (). The ESP8266 would then connect to the network. 


See also: 


wifi_wps_enable 

wifi_wps_start 

wifi_set_wps_cb 

Simple Questions: What is WPS (WiFi Protected Setup) 
Wikipedia: WiFi Protected Setup 





Designs for bootstrapping WiFi 

Imagine that we have built a project using an ESP32 that wishes to be network 
connected. In order for that to happen, we want the ESP32 to connect to an existing 
access point. That's works, because the ESP32 can be a WiFi station. In order for the 
ESP32 to connect to an access point, it needs to know two important items. It needs to 
know which network to join (the SSID) and it will need to know the password to use to 
connect to that network as most networks require authentication. And there is the 
puzzle. If the ESP32 is brought to a physically new environment, how will it "know" 
which network to connect with and what password to use? We should assume that the 
ESP32 doesn't have a screen attached to it. If it did, we could prompt the user for the 
information. 


One solution is to have the ESP32 initially "be" an access point. If it were an access 
point then we could use our phone to connect with it, ask it what WiFi networks it can 
see, provide a password for the network and allow it to connect. 


while (not done) { 
if (we know our ssid and password) { 
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attempt to connect to the access point; 
if (we succeeded in the connection) { 
return; 
} 
} 
become an access point ourselves; 
listen for incoming browser requests; 
wait for an SSID/password pair to be entered; 
} 
We also need to handle the case where we think we have an SSID and password used 
to connect to an access point but either those have changed or else we are in a foreign 
location. In that case we must also fall back to being an access point and await new 


instructions. 


We can use non-volatile storage to save our SSID and password. We may wish to save 
not just one SSID/password pair but perhaps save an ordered list. That way when we 
teach our device how to connect to an access point and then later teach it how to 
connect to another one, we might end up back at the first. For example, imagine using 
an ESP32 at home with one network and the same ESP32 at work with a different 
network. 


We may also want to save static interface information if we either don't have or don't 
want to use the services of a DHCP server when we start as a station. 


See also: 


Non Volatile Storage 


Working with TCP/IP 


TCP/IP is the network protocol that is used on the Internet. It is the protocol that the 
ESP32 natively understands and uses with WiFi as the transport. Books upon books 
have already been written about TCP/IP and our goal is not to attempt to reproduce a 
detailed discussion of how it works, however, there are some concepts that we will try 
and capture. 


First, there is the IP address. This is a 32bit value and should be unique to every device 
connected to the Internet. A 32bit value can be thought of as four distinct 8bit values (4 
x 8=32). Since we can represent an 8bit number as a decimal value between 0 and 
255, we commonly represent IP addresses with the notation 
<number>.<number>.<number>.<number> for example 173.194.64.102. These IP 
addresses are not commonly entered in applications. Instead a textual name is typed 
such aS "google.com" ... but don't be misled, these names are an illusion at the TCP/IP 
level. All work is performed with 32bit IP addresses. There is a mapping system that 
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takes a name (Such as "google.com") and retrieves its corresponding IP address. The 
technology that does this is called the "Domain Name System" or DNS. 


When we think of TCP/IP, there are actually three distinct protocols at play here. The 
first is IP (Internet Protocol). This is the underlying transport layer datagram passing 
protocol. Above the IP layer is TCP (Transmission Control Protocol) which provides the 
illusion of a connection over the connectionless IP protocol. Finally there is UDP (User 
Datagram Protocol). This too lives above the IP protocol and provides datagram 
(connectionless) transmission between applications. When we say TCP/IP, we are not 
just talking about TCP running over IP but are in fact using this as a shorthand for the 
core protocols which are IP, TCP and UDP and additional related application level 
protocols such as DNS, HTTP, FTP, Telnet and more. 


The Lightweight IP Stack - lwip 

If we think of TCP/IP as a protocol then we can break up our understanding of 
networking into two distinct layers. One is the hardware layer that is responsible for 
getting a stream of 1's and 0's from one place to another. Common implementations for 
that include Ethernet, Token Ring and (yes ... I'm dating myself now ... dial-up 
modems). These are characterized by physical wires from your devices. WiFi is itself a 
transport layer. It deals with using radio waves as the communication medium of 1's 
and 0's between two points. The specification for WiFI is IEEE 802.11. 


Once we can transmit and receive data, the next level is organizing the data over that 
physical network and this is where TCP/IP comes into play. It provides the rules and 
governance of data transmission, addressing, routing, protocol negotiations and more. 
Typically, TCP/IP is implemented in software over the underlying physical transport 
mechanism. Think about this a moment. Imagine | said to you that | have a "magic 
box" and if you put something in that box, it will magically be transported to a different 
box. That is the analogy of physical transport. The software that is TCP/IP adds 
mechanisms above that. For example, imagine the box is only 6 inches wide. If you 
want to send me something through our boxes, you have to chop it up and send it in 
pieces. Your end of the box story handles that. My box will receive the parts and re- 
assemble them for me. Parts may arrive in order and some parts may even get lost on 
route and have to be re-sent from the originals. The hardware (the boxes) have no idea 
how to achieve that. All they know is a piece of data in one end will hopefully arrive at 
the other ... but not guaranteed. 


TCP/IP is a big protocol. It contains lots of parts. Fortunately it is well specified and 
has been implemented by many vendors over the last 45 years. Some of the 
implementations of the whole stack of TCP/IP parts have been written as open source 
and are distributed and maintained by the community. What this means is that if one 
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has a new hardware layer, one can (in principle) lift an already written implementation of 
TCP/IP, map it to your hardware, compile it for your environment and you are good to 
go. This is actually much easier said than done ... and fortunately for us, our friends at 
Espressif have done the work for us. 


One such open source implementation of a TCP/IP stack is called "The 
LightweightIPStack" which is commonly referred to as "IwIP". This can be read about in 
detail at its home page (see the references). As part of the distribution of the ESP-IDF, 
we have libraries that provide an implementation IwIP. It is lwIP that provides the 
ESP32 the following services: 


¢ IP 

« ICMP 

¢ IGMP 

¢« MLD 

« ND 

¢ UDP 

* TCP 

¢ sockets API 
* DNS 


Again, the good news is that the vast majority of lwIP is of no importance to us, ESP32 
application designers and developers. It is vitally important ... but important to the 
internal operation of ESP32 and not exposed to us as consumers. 


See also: 


IwIP 2.0.0 


TCP 

A TCP connection is a bi-directional pipe through which data can flow in both directions. 
Before the connection is established, one side is acting as a server. It is passively 
listening for incoming connection requests. It will simply sit there for as long as needed 
until a connection request arrives. The other side of the connection is responsible for 
initiating the connection and it actively asks for a connection to be formed. Once the 
connection has been constructed, both sides can send and receive data. In order for 
the "client" to request a connection, it must know the address information on which the 
server is listening. This address is composed of two distinct parts. The first part is the 
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IP address of the server and the second part is the "port number" for the specific 
listener. If we think about a PC, you may have many applications running on it, each of 
which can receive an incoming connection. Just knowing the IP address of your PC is 
not sufficient to address a connection to the correct application. The combination of IP 
address plus port number provides all the addressing necessary. 


As an analogy to this, think of your cell phone. It is passively sitting there until someone 
calls it. In our story your phone is the listener. The address that someone uses to form 
a connection is your phone number which is comprised of an area code plus the 
remainder. For example, a phone number of (817) 555-1234 will reach a particular 
phone. However the area code of 817 is for Fort Worth in Texas ... calling that by itself 
is not sufficient to reach an individual ... the full phone number is required. 


No we will look at how an ESP32 can set itself up as a listener for an incoming TCP/IP 
connection and this requires that we begin to understand the important "sockets" API. 


TCP/IP Sockets 

The sockets API is a programming interface for working with TCP/IP networking. It is 
probably the most familiar API for network programming. Sockets programming is 
familiar to programmers on Linux, Windows, Java and more. 


TCP/IP network flows come in two flavors ... connection oriented over TCP and 
datagram oriented over UDP. The sockets API provides distinct patterns of calls for 
both styles. 


For TCP, a server is built by: 
1. Creating a TCP socket 
. Associating a local port with the socket 
. Setting the socket to listen mode 
. Accepting a new connection from a client 
. Receive and send data 


. Close the client/server connection 


N OO OO fF W DN 


. Going back to step 4 
For a TCP client, we build by: 


1. Creating a TCP socket 


2. Connecting to the TCP server 
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3. Sending data/receiving data 


4. Close the connection 


Now let us break these up into code fragments that we can analyze in more depth. The 
header definitions for the sockets API can be found in <lwip/sockets.h>. 


For both the client and the server applications, the task of creating a socket is the same. 
It is an API call to the socket () function. 


int sock = socket (AF INET, SOCK STREAM, IPPROTO_ TCP) 








The return from socket () is an integer handle that is used to refer to the socket. 
Sockets have lots of state associated with them, however that state is internal to the 
TCP/IP and sockets implementation and need not be exposed to the network 
programmer. As such, there is no need to expose that data to the programmer. We can 
think of calling socket () as asking the run-time to create and initialize all the data 
necessary for a network communication. That data is owned by the run-time and we 
are passed a "reference number" or handle that acts as a proxy to the data. When ever 
we wish to subsequently perform work on that network connection, we pass back in that 
handle that was previously issued to us and we can correlate back to the connection. 
This isolates and insulates the programmer from the guts of the implementation of 
TCP/IP and leaves us with a useful abstraction. 


When we are creating a server side socket, we want it to listen for incoming connection 
requests. To do this, we need to tell the socket which TCP/IP port number it should be 
listening upon. Note that we don't supply the port number a directly from an int/short 
value. Instead we supply the value as returned by the htons() function. What this 
function does is convert the number into what is called "network byte order". This is the 
byte order that has been chosen by convention to be that used for transmitting unsigned 
multi byte binary data over the internet. It's actual format is "big endian" which means 
that if we take a number such as 9876 (decimal) then it is represented in binary as 
00100110 10010100 or 0x26D4 in hex. For network byte order, we first transmit 
00100110 (0x26) followed by 10010100 (OxD4). It is important to realize that the ESP32 
is a little endian native architecture which means that we absolutely must transform 2 
byte and 4 byte numbers into network byte order (big endian). 


On a given device, only one application at a time can be using any given local port 
number. If we want to associate a port number with an application, such as our server 
application in this case, we perform a task called "binding" which binds (or assigns) the 
port number to the socket which in turn is owned by the application. 
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struct sockaddr_in serverAddress; 





serverAddress.sin family = AF_ INET; 

serverAddress.sin_addr.s_ addr = htonl(INADDR_ ANY); 
serverAddress.sin_ port = htons (portNumber) ; 

bind(sock, (struct sockaddr *) &serverAddress, sizeof (serverAddress) ); 





With the socket now associated with a local port number, we can request that the run- 
time start listening for incoming connections. We do this by calling the 1isten() API. 
Before calling 1isten(), connections from clients would have been rejected with an 
indication to the client that there was nothing at the corresponding target address. 
Once we call listen (), the server will start accepting incoming client connections. The 
API looks like: 


listen(sock, backlog) 


The backlog is the number of connection requests that the run-time will listen for and 
accept before they are handed off to the application for processing. The way to think 
about this is imagine that you are the application and you can only do one thing at a 
time. For example, you can only be talking to one person at a time on the phone. Now 
imagine you have a secretary who is handling your incoming calls. When a call arrives 
and you are not busy, the secretary hands off the call to you. Now imagine that you are 
busy. At that time, the secretary answers the phone and asks the caller to wait. When 
you free up, she hands you the waiting call. Now let us assume that you are still busy 
when yet another client calls. She also tells this caller to wait. We are starting to build a 
queue of callers. And this is where the backlog concept comes into play. The backlog 
instructs the run-time how many calls can be received and asked to wait. If more calls 
arrive than our backlog will allow, the run-time rejects the call immediately. Not only 
does this prevent run-away resource consumption at the server, it also can be used as 
an indication to the caller that it may be better served trying elsewhere. 


Now from a server perspective, we are about ready to do some work. A server 
application can now block waiting for incoming client connections. The thinking is that a 
server application's purpose in life is to handle client requests and when it doesn't have 
an active client request, there isn't anything for it to do but wait for a request to arrive. 
While that is certainly one model, it isn't necessarily the only model or even the best 
model (in all cases). Normally we like our processors to be "utilized". Utilized means 
that while it has productive work it can do, then it should do it. If the only thing our 
program can do is service client calls, then the original model makes sense. However, 
there are certain programs that if they don't have a client request to immediately 
service, might spend time doing something else that is useful. We will come back to 
that notion later on. For now, we will look at the accept () function call. When accept () 
is called, one of two things will happen. If there is no client connection immediately 
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waiting for us, then we will block until such time in the future when a client connection 
does arrive. At that time we will wake up and be handed the connection to the newly 
arrived client. If on the other hand we called accept () and there was already a client 
connection waiting for us, we will immediately be handed that connection and we carry 
on. In both cases, we call accept () and are returned a connection to a client. The 
distinction between the cases is whether or not we have to wait for a connection to 
arrive. 


The API call looks like: 


struct sockaddr _in clientAddress; 

socklen t clientAddressLength = sizeof (clientAddress) ; 

int clientSock = accept(sock, (struct sockaddr *) &clientAddress, 
é&éclientAddressLength) ; 








The return from accept () is a new socket (an integer handle) that represents the 
connection between the requesting client and the server. It is vital to realize that this is 
distinct from the server socket we created earlier which we bound to our server listening 
port. That socket is still alive and well and exists to continue to service further client 
connections. The newly returned socket is the connection for the conversation that was 
initiated by this single client. Like all TCP connections, the conversation is symmetric 
and bi-directional. This means that there is now no longer the notion of a client and 
server ... both parties can send and receive as they would like at any time. 


If we wish to create a socket client, the story is similar. Again we create a socket () but 
this time there is no need for a bind()/listen()/accept () story. Instead we use the 
connect () API to connect to the target TCP/IP endpoint. 


For example: 


struct sockaddr in serverAddress; 

serverAddress.sin family = AF_INET; 

inet _pton(AF INET, "192.168.1.200", &serverAddress.sin_addr.s_ addr); 
serverAddress.sin port = htons (9999) ; 








int rc = connect(sock, (struct sockaddr *)&serverAddress, sizeof(struct sockaddr_in)); 
See also: 


Native byte order, endian and network byte order 
socket 

bind 

listen 

accept 

send 

recv 

connect 
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Wikipedia — Berkeley Sockets 
Beej's Guide to Network Programming 





Handling errors 
Most of the sockets APIs return an int return code. If this code is < 0 then an error has 
occurred. 


The nature of the error can be found using the global int called "errno". However, in a 
multitasking environment, working with global variables is not recommended. In the 
sockets area, we can ask a socket for the last error it encountered using the following 
code fragment: 
int espx last socket _errno(int socket) { 

int ret = 0; 

u32_t optlen = sizeof (ret); 


getsockopt (socket, SOL SOCKET, SO ERROR, &ret, é&optlen); 
return ret; 














} 


The meanings of the errors can be compared against constants. Here is a table of 
constants used in the current FreeRTOS implementation: 




































































Symbol Value | Description 

EPERM 1 Operation not permitted 
ENOENT 2 No such file or directory 
ESRCH 3 No such process 
EINTR 4 Interrupted system call 
EIO 5 1/O error 

ENXIO 6 No such device or address 
E2BIG 7 Arg list too long 
ENOEXEC 8 Exec format error 
EBADF 9 Bad file number 
ECHILD 10 No child processes 
EAGAIN 11 Try again 

ENOMEM 12 Out of memory 
EACCES 13 Permission denied 
EFAULT 14 Bad address 
ENOTBLK 15 Block device required 
EBUSY 16 Device or resource busy 
EEXIST 17 File exists 

EXDEV 18 Cross-device link 
ENODEV 19 No such device 
ENOTDIR 20 Not a directory 
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EISDIR 21 Is a directory 

EINVAL 22 Invalid argument 

ENFILE 23 File table overflow 

EMFILE 24 Too many open files 
ENOTTY 25 Not a typewriter 

ETXTBSY 26 Text file busy 

EFBIG 27 File too large 

ENOSPC 28 No space left on device 
ESPIPE 29 Illegal seek 

EROFS 30 Read-only file system 
EMLINK 31 Too many links 

EPIPE 32 Broken pipe 

EDOM 33 Math argument out of domain of func 
ERANGE 34 Math result not representable 
EDEADLK 35 Resource deadlock would occur 
ENAMETOOLONG 36 File name too long 
ENOLCK 37 No record locks available 
ENOSYS 38 Function not implemented 
ENOTEMPTY 39 Directory not empty 

ELOOP 40 Too many symbolic links encountered 
EWOULDBLOCK EAGAIN 41 Operation would block 
ENOMSG 42 No message of desired type 
EIDRM 43 Identifier removed 
ECHRNG 44 Channel number out of range 
EL2NSYNC 45 Level 2 not synchronized 
EL3HLT 46 Level 3 halted 

EL3RST 47 Level 3 reset 

ELNRNG 48 Link number out of range 
EUNATCH 49 Protocol driver not attached 
ENOCSI 50 No CSI structure available 
EL2HLT 51 Level 2 halted 

EBADE 52 Invalid exchange 

EBADR 53 Invalid request descriptor 
EXFULL 54 Exchange full 

ENOANO 55 No anode 

EBADRQC 56 Invalid request code 
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EBADSLT 57 Invalid slot 

EBFONT 59 Bad font file format 

ENOSTR 60 Device not a stream 

ENODATA 61 No data available 

ETIME 62 Timer expired 

ENOSR 63 Out of streams resources 

ENONET 64 Machine is not on the network 
ENOPKG 65 Package not installed 

EREMOTE 66 Object is remote 

ENOLINK 67 Link has been severed 

EADV 68 Advertise error 

ESRMNT 69 Srmount error 

ECOMM 70 Communication error on send 
EPROTO 71 Protocol error 

EMULTIHOP 72 Multihop attempted 

EDOTDOT 73 RFS specific error 

EBADMSG 74 Not a data message 

EOVERFLOW 75 Value too large for defined data type 
ENOTUNIQ 76 Name not unique on network 
EBADFD 77 File descriptor in bad state 
EREMCHG 78 Remote address changed 

ELIBACC 719 Can not access a needed shared library 
ELIBBAD 80 Accessing a corrupted shared library 
ELIBSCN 81 .lib section in a.out corrupted 
ELIBMAX 82 Attempting to link in too many shared libraries 
ELIBEXEC 83 Cannot exec a shared library directly 
EILSEQ 84 Illegal byte sequence 

ERESTART 85 Interrupted system call should be restarted 
ESTRPIPE 86 Streams pipe error 

EUSERS 87 Too many users 

ENOTSOCK 88 Socket operation on non-socket 
EDESTADDRREQ 89 Destination address required 
EMSGSIZE 90 Message too long 

EPROTOTYPE 91 Protocol wrong type for socket 
ENOPROTOOPT 92 Protocol not available 
EPROTONOSUPPORT 93 Protocol not supported 
ESOCKTNOSUPPORT 94 Socket type not supported 
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EOPNOTSUPP 95 Operation not supported on transport endpoint 
EPFNOSUPPORT 96 Protocol family not supported 
EAFNOSUPPORT 97 Address family not supported by protocol 
EADDRINUSE 98 Address already in use 

EADDRNOTAVAIL 99 Cannot assign requested address 
ENETDOWN 100 Network is down 

ENETUNREACH 101 Network is unreachable 

ENETRESET 102 Network dropped connection because of reset 
ECONNABORTED 103 Software caused connection abort 
ECONNRESET 104 Connection reset by peer 

ENOBUFS 105 No buffer space available 

EISCONN 106 Transport endpoint is already connected 
ENOTCONN 107 Transport endpoint is not connected 
ESHUTDOWN 108 Cannot send after transport endpoint shutdown 
ETOOMANYREFS 109 Too many references: cannot splice 
ETIMEDOUT 110 Connection timed out 

ECONNREFUSED 111 Connection refused 

EHOSTDOWN 112 Host is down 

EHOSTUNREACH 113 No route to host 

EALREADY 114 Operation already in progress 
EINPROGRESS 115 Operation now in progress 

ESTALE 116 Stale NFS file handle 

EUCLEAN 117 Structure needs cleaning 

ENOTNAM 118 Not a XENIX named type file 

ENAVAIL 119 No XENIX semaphores available 

EISNAM 120 Is a named type file 

EREMOTEIO 121 Remote I/O error 

EDQUOT 122 Quota exceeded 

ENOMEDIUM 123 No medium found 

EMEDIUMTYPE 124 Wrong medium type 











Configuration settings 


Within the "menuconfig" there are some settings that relate to TCP/IP and can be found 
within the IwIP settings. The settings are: 
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¢ Max number of open sockets — integer — coNFIG_LWIP Max socKETs — This is the 
number of concurrently open sockets. The default is 4 and the maximum 
appears to be 16. 


¢ Enable SOQ. REUSEADDR - boolean — twip_so REUSE — 

















Using select() 

Imagine that we have multiple sockets each of which may be the source of incoming 
data. If we try and read() data from a socket, we normally block until data is ready. If 
we did this, then if data becomes available on another socket, we wouldn't know. An 
alternative is to try and read data in a non-blocking fashion. This too would be useful 
but would require that we test each socket in turn in a busy or polling fashion. This too 
is not optimal. Ideally what we would like to do is block while watching multiple sockets 
simultaneously and wake up when the first one has something useful for us to do. 


See also: 


select 
The world of select() 





Differences from "standard" sockets 
Two header files that are commonly found in other sockets implementations are not part 
of the ESP-IDF definition. They are: 


* netinet/in.h 
* arpa/inet.h 


Despite not being present, no obvious issues have been found and it is assumed that 
the content normally contained within has been distributed across other headers. 


UDP/IP Sockets 

If we think of TCP as forming a connection between two parties similar to a telephone 
call, then UDP is like sending a letter through the postal system. If | were to send you a 
letter, | would need to know your name and address. Your address is needed so that 
the letter can be delivered to the correct house while your name ensure that it ends up 
in your hands as opposed to someone else who may live with you. In TCP/IP terms, the 
address is the IP address and the name is the port number. 


With a telephone conversation, we can exchange as much or as little information as we 
like. Sometimes | talk, sometimes you talk ... but there is no maximum limit on how 
much information we can exchange in one conversation. With a letter however, there 
are only so many pages of paper that will fit in the envelopes | have at my disposal. 
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The notion of the mail analogy is how we might choose to think about UDP. The 
acronym stands for User Datagram Protocol and it is the notion of the datagram that is 
akin to the letter. A datagram is an array of bytes that are transmitted from the sender to 
the receiver as a unit. The maximum size of a datagram using UDP is 64KBytes. No 
connection need be setup between the two parties before data starts to flow. However, 
there is a down side. The sender of the data will not be made aware of a receiver's 
failure to retrieve the data. With TCP, we have handshaking between the two parties 
that lets the sender know that the data was received and, if not, can automatically re- 
transmit until it has been received or we decide to give up. With UDP, and just like a 
letter, when we send a datagram, we lose sight of whether or not it actually arrives 
safely at the destination. 


Now is a good time to come back to IP addresses and port numbers. We should start to 
be aware that on a PC, only one application can be listening upon any given port. For 
example, if my application is listening on port 12345, then no other application can also 
be listening on that same port ... not your application nor another copy/instance of mine. 
When an incoming connection or datagram arrives at a machine, it has arrived because 
the IP address of the sent data matches the IP address of the device at which it arrived. 
We then route within the device based on port numbers. And here is where | want to 
clarify a detail. We route within the machine based on the pair of both protocol and port 
number. 


So for example, if a request arrives at a machine for port 12345 over a TCP connection, 
it is routed to the TCP application watching port 12345. If a request arrives at the same 
machine for port 12345 over UDP, it is routed to the UDP application watching port 
12345. What this means is that we can have two applications listening on the same 
port but on different protocols. Putting this more formally, the allocation space for port 
numbers is a function of the protocol and it is not allowed for two applications to 
simultaneously reserve the same port within the same protocol allocation space. 
Although | used the story of a PC running multiple applications, in our ESP32 the story 
is similar even though we just run one application on the device. If your single 
application should need to listen on multiple ports, don't try and use the same port with 
the same protocol as the second function call will find the first one has already allocated 
the port. This is a detail that | am happy for you to forget as you will rarely come across 
it but | wanted to catch it here for completeness. 


To program with UDP, once again we use sockets. To set up a socket server using UDP 
again we call socket () to create a socket and again we call bind () to specify the port 
number we wish to listen upon. There is no need for a call to Listen(). When the 
server is ready to receive an incoming request, we call recvfrom() which blocks until a 
datagram is received. Once one arrives, we wake up and can process the request. 
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The request contains a return address and we can send a response using sendto () 
should we wish. 


On the client side, we create a socket () and then can invoke sendto(). The call to 
sendto() takes the IP address and port of the target as parameters as well as the 
payload data. 


For example: 


int socket fd = socket (AF INET, SOCK _DGRAM, 0); 
sendto(socket_fd, data, size, 0, destAddr, destAddrLen) ; 





socket 
sendto 
recvfrom 


TLS, SSL and security 

So far we have been thinking about making sockets calls that form a network 
connection and then sending and receiving data over that connection. However we 
have a security problem. The data that flows over the wire is not encrypted. This 
means that if one were to "sniff" or otherwise examine the network data, we would see 
the content of the data being transmitted. For example, if | send a password used for 
authentication, if we were to examine the content of the data, we would be able to 
determine the password | am using. 


Password 


1011011010110001 





It actually isn't that difficult to sense the data being sent and received. Excellent tools 
such as wireshark are used for debugging and can easily be used to examine the 
content of the network packets or stream. Obviously we are already exchanging credit 
card data, email and other sensitive information over the Internet so how is that done? 


The answer is a concept called the "Secure Socket Layer" or SSL. SSL provides the 
capability to encrypt the data before transmission such that only the intended recipient 
can decrypt it. Conversely, any responses sent by the recipient are also encrypted such 
that only we can decrypt the data. If someone were to capture or otherwise examine 
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the data being sent over the wire, there is no way for them to get back to the original 
data content. 


Password 
$5 TyH7#5 








1011011010110001 





The way this works is through the concept of private keys. Imagine | think of a very 
large random number (and by large | mean VERY large). We call this private number 
my private key. Now imagine that associated with the private key is a corresponding 
number (the public key) that can be used to decrypt a message that was encoded using 
the private key. Now imagine | want to correspond with a partner securely. | send a 
request (unencrypted) to the partner and ask for his public key. He sends that back and 
| send to him a copy of MY public key encrypted with his public key. Since only a 
matching pair of public/private keys can be used to decrypt data, only the desired 
recipient can decrypt the message at which point he will have a copy of my public key. 
Now in the future | can send him messages encrypted with my private key and further 
encrypted with his public key and he will be able to decode them with his copy of his 
private key and my public key while he can send me encrypted messages encoded with 
his private key which | can decode with my copy of his public key. By having 
exchanged public keys, we are now good to continue exchanging data without fear that 
it will be seen by anyone else. 


All of this encryption of data happens outside and above the knowledge of TCP/IP 
networking. TCP/IP provides the delivery of data but cares nothing about its content. 
As such, and at a high level, if we wish to exchange secure data, we must perform the 
encryption and decryption using algorithms and libraries that live outside of the sockets 
API and use sockets as the transport for transmitting and receiving the encrypted data 
that is fed into and received from the encryption algorithms. 


When using mbed TLS, we need a large stack size. | don't yet know how small we can 
get away with but | have been using 8000 bytes. 
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See also: 


mbed TLS 

mbed TLS home page 
mbed TLS tutorial 

mbed TLS API reference 








mbedTLS app structure 
Let us start to break down the structure of a TLS application that uses the mbedTLS 
APIs. 


First there is the notion of a network context that is initialized by a call to 
mbedtls net init(). 





mbedtls net context server fd; 
mbedtls net_init(&server fd); 


There is nothing more to explain here. The data that is initialized is "opaque" to us and 
the invocation of this function is part of the rules. 


next comes the initialization of the SSL context with a call to mbedt1ls_ssl_init(). 


mbedtls_ssl_ context ssl; 
mbedtls_ ssl _ init(é&ssl); 


Again, there is nothing more to explain here. The data is again opaque and this 
function merely initializes it for us. Calling this function is also part of the rules. 


Now we Call mebtls_ ssl confi g_init(). 





mbedtls_ssl_ config config; 
mbedtls ssl config init (&config) ; 


These initializations repeat for other data types including: 


mbedtls_ ctr _drbg_context ctr_drbg; 
mbedtls ctr _drbg init (&ctr_drbg) ; 


mbedtls entropy context entropy; 
mbedtls entropy init (&entropy) ; 


mbedtls x509 crt cacert; 
mbedtls x509 crt_init(&cacert); 





SSL utilizes good random number generators. What is a "good" random number? 
Since computers are deterministic devices, the generation of a random number is 
performed through the execution of an algorithm and since algorithms are deterministic, 
then a sequence of numbers generated by these functions might, in principle, be 
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predictable. A good random number generator is one where the sequence of numbers 
produced is not at all easily predictable and generates values with no biases towards 
their values with an equal probability of any number within a range being chosen. 


We initialize the random number generator with a call to mbedt1ls_ctr_drbg seed(). 





Note: We see the phrase "ctr drbg"... that is an acronym for "Counter mode Deterministic Random Byte 
Generator". It is an industry standard specification/algorithm for generating random numbers. 
http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-90Ar1 .pdf 














With the setup under our belts, it is now time to start considering SSL based 
communication. Since we are considering SSL over sockets, if we were not using TLS 
sockets, we would perform a call to socket () to create a socket and then connect () to 
connect to our partner. In the world of mbedtls, we call mbedtls_ net _connect(). This 
has the form: 














mbedtls net connect (&server fd, <hostname>, <port>, MBEDTLS NET PROTO TCP); 


The hostname and port define where we are connecting to. Notice the first parameter. 
This is the mbedtls_ net context structure that we initialized with a call to 
mbedtls net init () previously. We should always check the return code to ensure that 
the connection was successful. 





Now we get to configure our SSL defaults with a call to 
mbedtls_ssl_ config defaults(). For example: 


mbedtls_ ssl _ config defaults ( 
é&conf, 
MBEDTLS SSL IS CLIENT, 
MBEDTLS SSL TRANSPORT STREAM, 
MBED SSL PRESET DEFAULT) 









































When we are communicating via SSL, we commonly wish to validate that the 
credentials provided by our partner indicate that they are who they claim to be. This 
process is called authentication. We can define what kind of authentication we wish to 
perform by calling mbedt1s_ ssl conf authmode(). 


mbedtls_ssl_ conf _authmode(é&ssl, MBEDTLS SSL VERIFY NONE) 














Earlier we said that SSL is heavily dependent on a good random number generator. 
Now we tell the environment which random number generator we wish to use: 


mbedtls_ssl_ conf _rng(&ssl, mbedtls_ ctr_drbg_ random, &ctr_drbg) 
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Next we do some more SSL context setup by calling mbedtls_ssl_ set hostname(). 


mbedtls_ssl_set_hostname(&ssl, "name") 


Now we instruct the SSL environment which functions to use to send and receive data 
by calling mbedtls_ssl_ set bio(). 


mbedtls_ssl_set_bio(&ssl, &server fd, mbedtls_ net _send, mbedtls_net_recv, NULL) 





At this point, we have formed a connection to our partner and configured the SSL 
environment. What remains is to actually read and write data. To write data we call 


mbed_ ssl _write(). 


mbedtls_ ssl write(&ssl, buf, len) 


and to read data we call mbedt1ls_ssl_read(). 


mbedtls_ ssl read(&ssl, buf, len) 


See also: 


mbedtls_net_init 
mbedtls_ssl_init 
mbedtls_ssl_config_init 
mbedtls_net_connect 
mbedtls_ssl_config_defaults 
mbedtls_ssl_conf_authmode 
mbedtls_ssl_conf_rng 
mbedtls_ssl_set_hostname 
mbedtls_ssl_set_bio 
mbedtls_ssl_write 
mbedtls_ssl_read 


mbedTLS Example 
Here is a sample function that has been tested on an ESP32 to make an HTTPS call to 
an HTTPS server to retrieve some results. 


#include "mbedtls/platform.h" 


#include "mbedtls/ctr_drbg.h" 
#include "mbedtls/debug.h" 
#include "mbedtls/entropy.h" 
#include "mbedtls/error.h" 
#include "mbedtls/net.h" 
#include "mbedtls/ssl.h" 
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#include "esp _log.h" 
#include "string.h" 
#include "stdio.h" 


#define SERVER_NAME "httpbin.org" 
#define SERVER_PORT "443" 
static char tag[] = "callhttps"; 


static char errortext[256]; 


static void my debug(void *ctx, int level, const char *file, int line, const char *str) 


((void) level); 
((void) ctx); 


2 


printf ("%s:%04d: %s", file, line, str); 


void callhttps() { 

ESP _LOGD(tag, "--> callhttps\n"); 
mbedtls net_context server_fd; 
mbedtls entropy context entropy; 
mbedtls_ctr_drbg_ context ctr_drbg; 
mbedtls_ssl_ context ssl; 
mbedtls_ssl_ config conf; 
mbedtls_ x509 crt cacert; 


int ret; 

int len; 

char *pers = "ssl_clientl"; 
unsigned char buf[1024]; 


bedtls net_init(&server fd); 

bedtls_ ssl _init(&ssl); 

bedtls_ ssl config init (&conf); 

bedtls x509 crt_init(&cacert); 

bedtls ctr _drbg init (&ctr_drbg); 

bedtls entropy init (&entropy) ; 
bedtls_ssl_conf_dbg(&conf, my debug, stdout); 


333432423328 








mbedtls_debug_set_threshold(2); // Log at error only 
ret = mbedtls_ctr_drbg_ seed ( 

&ctr_drbg, 

mbedtls entropy func, &entropy, (const unsigned char *) pers, strlen(pers)); 
if (ret != 0) { 
ESP_LOGE(tag, " failed\n ! mbedtls_ctr_drbg seed returned %d\n", ret); 
return; 


ret = mbedtls_net_connect (&server_fd, SERVER_NAME, SERVER_PORT, MBEDTLS_ NET PROTO_TCP); 


if (ret != 0) { 
ESP_LOGE(tag, " failed\n ! mbedtls_ net connect returned %d\n\n", ret); 
return; 





ret = mbedtls_ssl_ config defaults ( 
&conf, 
MBEDTLS SSL_IS CLIENT, 
MBEDTLS_SSL_TRANSPORT_STREAM, 
MBEDTLS SSL PRESET DEFAULT) ; 
if (ret != 0) { 
ESP_LOGE(tag, " failed\n ! mbedtls_ssl_ config defaults returned %d\n\n", ret); 
return; 


mbedtls_ssl_conf_authmode(éconf, MBEDTLS_ SSL_VERIFY_NONE) ; 


mbedtls_ssl_conf_rng(&conf, mbedtls_ctr_drbg_random, &ctr_drbg); 


{ 
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ret = mbedtls_ssl_setup(&ssl, &conf); 

if (ret != 0) { 
mbedtls_ strerror(ret, errortext, sizeof (errortext)); 
ESP_LOGE(tag, "error from mbedtls_ssl_setup: %d - %x - %s\n", ret, ret, errortext); 
return; 


} 


ret = mbedtls_ssl_set_hostname(&ssl, "httpbin.org"); 
if (ret != 0) { 
mbedtls_strerror(ret, errortext, sizeof (errortext) ); 
ESP_LOGE(tag, "error from mbedtls_ssl_set_hostname: %d - %x - Ss\n", ret, ret, errortext); 





return; 


} 
mbedtls_ssl_set_bio(&ssl, &server fd, mbedtls_ net send, mbedtls_ net_recv, NULL); 


char *requestMessage = \ 
"GET /ip HTTP/1.1\r\n" \ 
"User-Agent: kolban\r\n" \ 
"Host: httpbin.org\r\n" \ 
"Accept-Language: en-us\r\n" \ 
"Accept-Encoding: gzip, deflate\r\n" \ 
wyr\n"; 

sprintf((char *)buf, requestMessage) ; 

len = strlen((char *)buf); 


ret = mbedtls_ssl_write(&ssl, buf, len); 

af {ret < Op 4 
mbedtls_ strerror(ret, errortext, sizeof (errortext)); 
ESP_LOGE(tag, "error from write: *d -%x - %s\n", ret, ret, errortext); 
return; 


} 


len = sizeof (buf); 

ret = mbedtls_ssl_read(&ssl, buf, len); 

if (ret < 0) { 
ESP_LOGE(tag, “error from read: Sd\n", len); 
return; 


} 

printf ("Result:\n%.*s\n", len, buf); 
mbedtls net_free(&server fd); 
mbedtls_ssl_ free(&ssl); 
mbedtls_ssl_ config free(&conf) ; 
mbedtls_ctr_drbg_ free(é&ctr_drbg); 
mbedtls entropy free(&entropy) ; 


ESP_LOGV(tag, "All done"); 
} 


Notes: 
When debugging MBED in Curl set MBEDTLS_DEBUG to 1 in curl_config.h 


OpenSSL 

OpenSSL is a popular implementation of an SSL stack. In the ESP32 environment, the 
selected stack for SSL/TLS is mbedTLS which is not the same as OpenSSL. As part of 
the ESP-IDF, a mapping layer has been provided that exposes the OpenSSL API on top 
of an mbedTLS implementation. 
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Name Service 

On the Internet, server machines can be found by their Domain Name Service (DNS) 
names. This is the service that resolves a human readable representation of a machine 
such as "google.com" into the necessary IP address value (eg. 216.58.217.206). In 
order for this transformation to happen, the ESP32 needs to know the IP address of one 
or more DNS servers that it will then use to perform the name to IP address mapping. If 
we are using DHCP then nothing else need be done as the DHCP server automatically 
provides the DNS server addresses. However, if we should not be using DHCP (for 
example we are using static IP addresses), then we need to instruct the ESP32 of the 
locations of the DNS servers manually. We can do this using dns_setserver() function. 
This takes an IP address as input along with which of the two possible DNS servers to 
use. The ESP32 is configured to know the identity of up to two external name servers. 
The reason for two is that if an attempt to reach the first one fails, we will utilize the 
second one. We can retrieve our current DNS server identities using dns_getserver(). 


Google publicly makes available two name servers with the addresses of 8.8.8.8 and 
8.8.4.4. 


Once we have define the name servers, we can look up the address of a host name 
using the gethostbyname () function. 


During development, we may wish to test a specific DNS server to validate that it can 

resolve a host name. An excellent Linux tool to perform this task is "nslookup". It has 
many options but for our purposes, we can supply it the host name to lookup and the 

DNS server to use: 


$ nslookup example.com 8.8.8.8 
Server: 8.8.8.8 
Address: 8.8.8.8#53 


Non-authoritative answer: 
Name: example.com 
Address: 93.184.216.34 


See also: 


gethostbyname 

dns_getserver 

dns_setserver 

Wikipedia: Domain Name System 
Google: Public DNS 








Multicast Domain Name Systems 
On a local area network with dynamic devices coming and going, we may want one 
device to find the IP address of another device so that they may interact with each 
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other. The problem though is that IP addresses can be dynamically allocated by a 
DHCP server running on a WiFi access point. This means that the IP address of a 
device is likely not going to be static. In addition, it is not a great usability story to refer 
to devices by their IP addresses. What we need is some form of dynamic name service 
for finding devices by name where their IP addresses aren't administrator configured. 
This is where the Multicast Domain Name System (mDNS) comes into play. 


At a high level, when a device wishes to find another device with a given name, it 
broadcasts a request to all members of the network asking for a response from the 
device that has that name. If a machine believes it has that identity, it responds with its 
own broadcast which includes its name and IP address. Not only does this satisfy the 
original request, but other machines on the network can see this interaction and cache 
the response for themselves. This means that should they need to resolve the same 
host in the future, they already have the answer. 


Using the Multicast Domain Name System (mDNS) an ESP32 can attempt to resolve a 
host name of a machine on the local network to its IP address. It does this by 
broadcasting a packet asking for the machine with that identity to respond. 


The name service demons are implemented by Bonjour and nss-mdns (Linux). 
Normally, hosts located using this technique belong to a domain ending in ".local". 


To determine if your PC is participating in mDNS you can examine whether or not it is 
listening on UDP port 5353. This is the port used for mDNS communications. 


See also: 


Wikipedia — Multicast DNS 

IETF RFC 6762: Multicast DNS 

Multicast DNS 

New DNS Technologies in the Lan 

Avahi — Implementation of mDNS ... source project for Unix machines 
Adafruit — Bonjour (Zeroconf) Networking for Windows and Linux 
chrome.mdns — API description for Chrome API for mDNS 

Android — ZeroConf Browser 








mDNS API programming 

The ESP-IDF provides a set of rich APIs for programming mDNS on the ESP32. 
Specifically, we can either advertise ourselves in mMDNS or else query existing mDNS 
information. 


The attributes of an mMDNS server entry appear to be: 
* hostname — mdns_set_hostname() 
¢ default instance — mdns_set_instance() 


* service —mdns_service_add() 
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° type —_http, ftp etc etc 

© protocol—_tcp, udp etc etc 

© port — port number 
* instance name for service — mdns_service_instance_set() 
¢ TXT data for service —mdns_service_txt_set() 


See also: 


. mdns_set_hostname 

. mdns_set_instance 

. mdns_service_add 

. mdns_service_instance_set 
. mdns_service_port_set 


Installing Bonjour 
Launch the Bonjour installer: 


# Bonjour64 








Welcome to the Bonjour Installer 


You will be guided through the steps necessary to install 
Bonjour. To get started, click Next. 





3.1.0.1 x64 
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License Agreement 


Please read the following license agreement carefully. 








APPLE INC. 
SOFTWARE LICENSE AGREEMENT FOR BONJOUR FOR 
WINDOWS 


PLEASE READ THIS SOFTWARE LICENSE AGREEMENT 
("LICENSE") CAREFULLY BEFORE USING THE APPLE 

SOFTWARE. BY USING THE APPLE SOFTWARE, YOU ARE 
AGREEING TO BE BOUND BY THE TERMS OF THIS LICENSE. IF 

YOU NO NOT AGRFF TO THF TFRMS OF THISIICFNSF NONOT ~ 


~) I do not accept the terms in the license agreement 

















Please read the following information. 





About Bonjour 





The Bonjour for Windows package provides Bonjour zero- 
configuration networking services for use by Windows 
applications such as iTunes, Safari and AirPort Utility. 


Bonjour enables computers and devices to automatically 
discover each other using industry standard IP protocols 
without the need to manually enter IP addresses or configure 
DNS servers. It is particularly useful for connecting to 

devices such as the iPhone, Apple TV. and AirPort base ¥. 
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Congratulations. 


Bonjour has been successfully installed on your computer. 


Click Finish to quit this Installer. 














es oe 











If all has gone well, we will find a new Windows service running called "Bonjour 


Service": 








File Action View Help 





¢9\HiSaslibml> aun 


Bonjour Service 


Stop the service 
Restart the service 


Description: 

Enables hardware devices 
and software services to 
automatically configure 
themselves on the network 
and advertise their presence. 





| Name 





‘G, AT&T Network Conf... 
‘© Background Intellig... 
‘© Base Filtering Engine 
‘©, BitLocker Drive Encr... 
©; Block Level Backup ... 


‘, Bluetooth Support S... 


‘ BranchCache 

©; Certificate Propagat... 
© CNG Key Isolation 

‘© COM+ Event System 
‘©, COM System Appii... 
© Computer Browser 
‘©, Credential Manager 
©, Cryptographic Servi... 


Description 

Service used for cellular and wi-... 
Transfers files in the backgroun... 
The Base Filtering Engine (BFE) ... 
BDESVC hosts the BitLocker Dri... 
The WBENGINE service is used ... 
The Bluetooth service supports ... 
Enables hard sices and s 
This service caches network con... 
Copies user certificates and roo... 
The CNG key isolation service is... 
Supports System Event Notifica... 
Manages the configuration and ... 
Maintains an updated list of co... 
Provides secure storage and ret... 
Provides four management serv... 





< 


Started 

















There is also a Bonjour browser available here ... 





http://hobbyistsoftware.com/bonjourbrowser 


Avahi 
An implementation of Multicast DNS on Linux is called Avahi. Avahi runs as the systema 
daemon called "avahi-daemon". We can determine whether or not it is running with: 


S$ systemctl status avahi-daemon 
e avahi-daemon.service - Avahi mDNS/DNS-SD Stack 
Loaded: loaded (/lib/systemd/system/avahi-daemon.service; enabled) 
Active: active (running) since Wed 2016-01-20 22:13:35 CST; 1 day 13h ago 
Main PID: 384 (avahi-daemon) 
Status: "avahi-daemon 0.6.31 starting up." 





CGroup: /system.slice/avahi-daemon.service 
+384 avahi-daemon: running [raspberrypi.local] 
L426 avahi-daemon: chroot helper 
The avahi-daemon utilizes a configuration file found at /etc/avahi/avahi-daemon.conf. 
The default name that avahi advertizes itself as is the local hostname. 


When host-name resolution is performed, the system file called /etc/nsswitch.conf is 
used to determine the order of resolution. Specifically the hosts entry contains the 
name resolution. An example would be: 


hosts: files mdns4 minimal [NOTFOUND=return] dns 


Which says "first look in /etc/hosts, then consult mDNS and then use full DNS". What 
this means is that a device which advertizes itself with mDNS can be found via a lookup 
of "<hostname>.local". For example, if | boot up a Linux machine which gets a dynamic 
IP address through DHCP and the hostname of that machine is "chip1", then | can 
reach it with a domain name address of "chipi.local". If the IP address of the device 
changes, subsequent resolutions of the domain name will continue to correctly resolve. 


Avahi tools are not installed by default but can be installed using the "avahi-utils" 
package: 
S sudo apt-get install avahi-utils 


To see the list of mDNS devices in your network, we can use the avahi-browse 
command. For example: 





























S$ avahi-browse -at 

+ wlanl IPv6 chipl [ce:79:cf:21:db:95 Workstation local 
+ wlanl IPv4 chipl [ce:79:cf:21:db:95 Workstation local 
+ wlan0O IPv6 pizero [00:36:76:21:97:a3] Workstation local 
+ wlan0O IPv6 raspi3 [b8:27:eb:9d:fc:60] Workstation local 
+ wlanO IPv6é chipl [cc:79:cf:21:db:95 Workstation local 
+ wlan0O IPv4 pizero [00:36:76:21:97:a3] Workstation local 
+ wlan0O IPv4 raspi3 [b8:27:eb:9d:fc:60] Workstation local 
+ wlanO IPv4 chipl [cc:79:cf:21:db:95 Workstation local 
+ wlan0O IPv6 pizero Remote Disk Management 
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local 











+ wlan0d IPv6 raspi3 Remote Disk Management 
local 

+ wlanOd IPv4 raspi3 Remote Disk Management 
local 

+ wlanO IPv4 pizero Remote Disk Management 
local 

+ wlan0O IPv4 WDMyCloud Apple File Sharing local 
+ wlanO IPv4 WDMyCloud _wd-2go. tcp local 
+ wlan0O IPv4 WDMyCloud Web Site local 
+ wlan0O IPv4 Living Room _googlecast. tcp local 
+ wlanO IPv4 123456789 _teamviewer. tcp local 


To access an mDNS advertized server from Microsoft Windows, you will need a service 
similar to Apple's Bonjour installed. Bonjour is distributed as part of Apple's iTunes 
product. Once installed, we should be able to access the published servers at their 
<name>. local address. A partner windows tool called "Bonjour Browser" is available 
which displays an mDNS listing of servers on windows. 


See also: 
* avahi home page 
* man(1)—avahi-browse 
* man(5) — avahi-daemon.conf 





Working with SNTP 

SNTP is the Simple Network Time Protocol and allows a device connected to the 
Internet to learn the current time. In order to use this, you must know of at least one 
time server located on the Internet. The US National Institute for Science and 
Technology (NIST) maintains a number of these which can be found here: 


http://tf.nist.gov/tf-cgi/servers.cgi 





Other time servers can be found all over the globe and | encourage you to Google 
search for your nearest or country specific server. 


Once you know the identity of a server by its host name or IP address, you can call 
either of the functions called sntp setservername() Of sntp setserver() to declare that 
we wish to use that time server instance. The ESP32 can be configured with up to 
three different time servers so that if one or two are not available, we might still get a 
result. 


The ESP32 must also be told the local timezone in which it is running. This is set with a 
Call to sntp_set timezone () which takes the number of hours offset from UTC. For 
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example, | am in Texas and my timezone offset becomes "-5". Although this function is 
present, | would suggest using the POSIX tzset () function instead. 


With these configured, we can start the SNTP service on the ESP32 by calling 

sntp init(). This will cause the device to determine its current time by sending 
packets over the network to the time servers and examining their responses. It is 
important to note that immediately after calling sntp_ init (), you will not yet know what 
the current time may be. This is because it may take a few seconds for the ESP32 to 
sends the time requests and get their responses and this will all happen asynchronously 
to your current commands and won't complete till sometime later. 


When ready, we can retrieve the current time with a call to 

sntp get current timestamp () which will return the number of seconds since the 1* of 
January 1970 UTC. We can also call the function called sntp_ get _real_time() which 
will return a string representation of the time. While these functions obviously exist, | 
would not recommend using them. Instead look at the POSIX alternatives which are 
time() and asctime(). 


Here is an example of using SNTP to set the time: 


ip addr _t addr; 

sntp_setoperatingmode (SNTP_OPMODE POLL) ; 
inet _pton(AF_ INET, "129.6.15.28", saddr); 
sntp_setserver(0, é&addr); 

sntp_init(); 








The time can be accessed from a variety of POSIX compliant functions including: 
* asctime — Build a string representation of time. 
* clock — Return processor time. 
* ctime — Build a string representation of time. 
* difftime — Calculate a time difference. 
* gettimeofday — Retrieve the current time of day. 
* gmtime — Produce a struct tm from a time_t. 
* localtime — Produce a struct tmfrom atime t. 
* settimeofday — Set the current time. 
* strftime —Formata time t toa string. 
* time — Get the current time as a time t (Seconds since epoch). 


See also: 


SNTP API 
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Timers and time 
asctime 
ctime 
gmtime 
localtime 
. strftime 
. IETF RFC5905: Network Time Protocol Version 4: Protocol and Algorithms Specification 





Java Sockets 

The sockets API is the defacto standard API for programming against TCP/IP. My 
programming language of choice is Java and it has full support for sockets. What this 
means is that | can write a Java based application that leverages sockets to 
communicate with the ESP32. | can send and receive data through quite easily. 


In Java, there are two primary classes that represents sockets, those are 
java.net.Socket which represents a client application which will form a connection and 
the second class is java.net.ServerSocket which represents a server that is listening 
on a socket awaiting a client connection. Since the ESP32 can be either a client or a 
server, both of these Java classes will come into play. 





To connect to an ESP32 running as a server, we need to know the IP address of the 
device and the port number on which it is listening. Once we know those, we can 
create an instance of the Java client with: 


Socket clientSocket = new Socket (ipAddress, port); 





This will form a connection to the ESP32. Now we can ask for both an InputStream 
from which to receive partner data and an outputStream to which we can write data. 





InputStream is = clientSocket.getInputStream(); 
OutputStream os = clientSocket.getOutputStream() ; 





When we are finished with the connection, we should call close () to close the Java side 
of the connection: 


clientSocket.close(); 





It really is as simple as that. Here is an example application: 


package kolban; 
import java.io.OutputStream; 
import java.net.Socket; 
import org.apache.commons.cli.CommandLine; 
import org.apache.commons.cli.CommandLineParser; 


import org.apache.commons.cli.DefaultParser; 





Gh GE AG set 


import org.apache.commons.cli.Options; 
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public class SocketClient { 


private String hostname; 


private int port; 


public static void main(String[] args) { 


} 


Options options = new Options(); 
options.addOption("h", true, "hostname") ; 


options.addOption("p", true, "port"); 





CommandLineParser parser = new DefaultParser(); 
try { 





CommandLine cmd = parser.parse(options, args); 


SocketClient client = new SocketClient(); 
client.hostname = cmd.getOptionValue("h") ; 

client.port = Integer.parselInt (cmd.getOptionValue ("p")); 
client.run(); 








} catch (Exception e) { 


} 





e.printStackTrace(); 














public void run() { 

try { 
int SIZE = 65000; 
byte data[] = new byte[SIZE]; 
for (int: 2.°= 07° a2. < SIZE? i++) { 

data[i] = 'X'; 

} 
Socket sl = new Socket (hostname, port); 


} 


fea/ fe 








OutputStream os = sl.getOutputStream(); 
os.write (data); 

sl.close(); 

System.out.println("Data sent!"); 


} catch (Exception e) { 


} 





e.printStackTrace(); 


End of class 


// End of file 





To configure a Java application as a socket server is just as easy. This time we create 
an instance of the socketServer Class using: 





SocketServer serverSocket = new SocketServer (port) 


The port supplied is the port number on the machine on which the JVM is running that 
will be the endpoint of remote client connection requests. Once we have a 
ServerSocket instance, we need to wait for an incoming client connection. We do this 
using the blocking API method called accept (). 


Socket partnerSocket = serverSocket.accept(); 
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This call blocks until a client connect arrives. The returned partnerSocket Is the 
connected socket to the partner which can used in the same fashion as we previously 
discussed for client connections. This means that we can request the InputStream and 
OutputStream Objects to read and write to and from the partner. Since Java is a multi- 
threaded language, once we wake up from accept () we Can pass off the received 
partner socket to a new thread and repeat the accept () call for other parallel 
connections. Remember to close() any partner socket connections you receive when 
you are done with them. 


So far, we have been talking about TCP oriented connections where once a connection 
is opened it stays open until closed during which time either end can send or receive 
independently from the other. Now we look at datagrams that use the UDP protocol. 


The core class behind this is called DatagramSocket. Unlike TCP, the DatagramSocket 
class is used both for clients and servers. 


First, let us look at a client. If we wish to write a Java UDP client, we will create an 
instance of a DatagramSocket USINQ: 





DatagramSocket clientSocket = new DatagramSocket (); 


Next we will "connect" to the remote UDP partner. We will need to know the IP address 
and port that the partner is listening upon. Although the API is called "connect", we 
need to realize that no connection is formed. Datagrams are connectionless so what 
we are actually doing is associating our client socket with the partner socket on the 
other end so that when we actually wish to send data, we will know where to send it to. 





clientSocket.connect (ipAddress, port); 


Now we are ready to send a datagram using the send() method: 


DatagramPacket data = new DatagramPacket (new byte[100], 100); 
clientSocket.send(data); 


To write a UDP listener that listens for incoming datagrams, we can use the following: 





DatagramSocket serverSocket = new DatagramSocket (port) ; 


The port here is the port number on the same machine as the JVM that will be used to 
listen for incoming UDP connections. 


To wait for an incoming datagram, call receive (). 


DatagramPacket data = new DatagramPacket (new byte[100], 100); 





clientSocket.receive (data) ; 


If you are going to use the Java Socket APIs, read the JavaDoc thoroughly for these 
classes are there are many features and options that were not listed here. 


See also: 
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Java tutorial: All About Sockets 
JDK 8 JavaDoc 





Bluetooth 


The ESP32 has native Bluetooth support (version 4.2). This means that it can interact 
with Bluetooth devices such as keyboards, mice and cell phones. Let us review what 
Bluetooth means for us. Bluetooth is a wireless communication protocol/technology that 
provides data transfer over a radio signal. Let us assume that ESP32 is one end of the 
connection and any other Bluetooth device can be at the other. For security purposes, 
arbitrary Bluetooth devices can't simply be "used" without some explicit authorization. 
For example, it would be very wrong if | could bring my Bluetooth headset near your 
phone and start listening to your calls. To achieve security, a process called "pairing" 
needs to be performed. This achieves a level of trust between the two Bluetooth 
devices such that they subsequently allow connection without having to be re-paired. 


Bluetooth specification 

Bluetooth is a specification for wireless communication between multiple electronic 
devices. At present, there are two primary standards ... these are Bluetooth (Classic) 
and Bluetooth LE. The "LE" stands for Low Energy and is the specification for devices 
that wish to be powered by simple batteries and yet have sufficient life span. 


In the Bluetooth story, we have devices which are "masters" and devices which are 
"slaves". Aslave can only form a connection and communicate with a master while a 
master can form concurrent connections with multiple slaves. One slave can not 
directly communicate with another slave. Instead it must communicate with the master 
and the master relay the request. 


The simplest communication is one master and one slave but if we have multiple slaves 
connected to the same master, the resulting "network" is termed a "piconet". 


Each device that participates in the conversation has a unique address that is a 48 bit 
value commonly written as 12 hex values (6 bytes). This address is known as the 
"Bluetooth Device Address" and may be seen in other documentation abbreviated to 
"BD ADDR". 


The encoding of a Bluetooth address is that the first 24 bits encode the organization 
responsible for allocating the remaining address and the remaining 24 bits are the 
address itself. However the full 48 bits are the complete identity of the device. 


As well as having a unique address, each device can have a symbolic name to help us 
meaningfully identify it. This is termed the display name. The display name is only a 
mapping to a Bluetooth address and it is really the address that is used to distinguish 
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one device from another. It is also important to note that there are no uniqueness 
constraints on device names. Multiple devices may select the same device name. 


Let us assume that initially, we have two devices and neither of them know about the 
other. What must now happen is a discovery process. One of them will broadcast an 
"inquiry" request. Devices receiving the inquiry can respond with their own existence by 
transmitting their own address and possibly additional information. It is common that 
the response to an inquiry does not contain the display name of the responding device. 
If the display name is needed, the inquirer can transmit a directed request now that it 
knows the address of the responding device which will solicit the name as a further 
response. 


A device does not have to respond to an inquiry request. It has a property setting called 
an "inquiry scan" that controls whether or not it responds to such. If the attribute is on, 
then it will respond to an inquiry request and if off, then it will not respond. Think of the 
phrase "inquiry scan" as the devices choice as to whether it performs the action of 
"scanning for inquires". 


Once the two devices know each other's addresses, a connection can be formed 
between them through a process known as "paging". Again, a device does not have to 
service a received connection request. It has a property setting called a "paging scan" 
which controls this. If on, then a paging request causes a new connection to be formed. 
If off, it will not accept a new connection request. 


Once a connection is formed between the devices, that connection can be maintained in 
a variety of states, the most common being active. However other states are available 
and are used to save power when there is no active communication of data anticipated. 


In order to permit devices to communicate with each other, there has to be an element 
of security involved. We usually don't want arbitrary devices to be able to connect with 
each other and share arbitrary information. To achieve this, a process called "bonding" 
is enacted. Bonding is achieved through the notion of "pairing". In pairing, the devices 
exchange their addresses, names and other data and generate keys that they share 
with each other. Pairing typically requires an explicit interaction from the user to permit 
the pairing to succeed. The user interaction can be as simple as "I approve this device" 
with a button click or it can be richer with the entry of a pass-code to authenticate and 
prove that one is who one claims to be. 


The Bluetooth protocol provides support for different classes of power. This translates 
directly into the signal strength of the radio. Remember that the more power used by 
the radio, the heavier the drain on the power source. If the power source is batteries, 
the more power used to transmit data, the shorter the life of the batteries. 
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At the lower levels, Bluetooth takes care of exchanging data between partners. 
However, there is much more to Bluetooth than just simple data exchange. In order to 
provide interoperability between devices built by multiple manufacturers, higher level 
protocols called "profiles" have been defined. These profiles define "what" is 
transmitted over Bluetooth for a given device function. 


Some of the profiles we will come across include: 
¢ usp —Head Set Profile (eg. a Bluetooth ear piece). 
¢ HFp—Hands Free Profile (eg. Bluetooth communication in a car). 
* HID —Human Interface Device (eg. a keyboard or mouse). 


¢ spp — Serial Port Profile. 





* a2pp —Advanced Audio Distribution profile (eg. connection to Bluetooth 
speakers). 


* avrcp —Audio Visual Remote Control Profile. 


Knowing that these protocols exist, it is not sufficient that two Bluetooth devices are in 
range of each other, they must also both support the same profile that is desired to be 
used. 


At a higher level that the connection are the transport protocols available to us. These 
include: 


* RFcCOoMM — Radio Frequency Communications Protocol. This protocol provides a 
reliable stream oriented transmission. Loosely, you can compare it to TCP. 


¢ 12cap —Logical Link Control and Adaption Protocol. This is a packet oriented 
protocol. RFCOMM builds on L2CAP. 


* act —Asynchronous Connection oriented Logical protocol. L2CAP builds on 
ACL. 


* sco — Voice quality audio protocol. 


To allow multiple conversations to be processed in parallel, the concept of the "port" is 
introduced. This is similar to a TCP/IP port number. L2CAP ports can be odd 
numbered values between 1 and 32767. For RFCOMM, the port numbers are called 
channels and are between 1 and 30. In the Bluetooth documentation, ports are referred 
to as "Protocol Service Multiplexers" or "PSMs". 


Certain port numbers used by L2CAP are designated as reserved for well defined 
purposes. 


See also: 
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Introduction to Bluetooth Low Energy 





Bluetooth UUIDs 
A UUID is a 16 byte number (128 bits). They are commonly written in hexadecimal with 
1 byte corresponding to 2 hex digits. The most common written format is 4-2-2-2-6. 


XXXXXKKXX-KXKX-KXKKK-KKKK-KKKK KKK KKKKMK 


When one receives a UUID, it is the value of the UUID that is used to describe the 
nature of the service or data. Each different type of service will have its own unique 
UUID. 


To reduce transmission overhead, the specification defines some well described 
services. If one implements one of those services, then we don't need to transmit the 
whole 128 bit UID but can get away with less. A special UUID of the form: 


XXXXXXXX-0000-1000-8000-00805F9BE4FB 


is available where only the first 4 bytes (32 bits) are needed to identify the type of 
service. 


Bluetooth GAP 

The Generic Access Protocol (GAP). It is GAP that determine which devices can 
interact with each other. Inthe GAP story there are primarily two classes of "things". 
There is the central device and the peripheral device. 


We can send advertizing using the Advertizing Data payload or the Scan Response 
payload. 


A peripheral device will constantly transmit its advertizing payload which can contain up 
to 31 bytes of data. The peripheral transmits its advertizing data every advertizing 
interval period. The Advertizing Data payload is present in all BT devices. If the central 
receiver of the advertizing data payload wishes, it can request a scan response and the 
peripheral will send back a scan response payload. 


When a peripheral is transmitting advertizing data, we can think of it as being in the 
mode of broadcasting. It is transmitting its data which may or may not be seen by a 
corresponding observer. 


The concept of BLE advertizing is powerful beyond just finding devices to form 
subsequent connections. The advertizing packets can contain data in their payload. If 
the data being transmitted does not need to be secure (for example, the outside 
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temperature), then we have the core of an interesting solution in its own right. The 
peripheral can simply broadcast its packets of data and the central can receive them 
without the need to form a connection. The receiver can then examine the payload and 
receive the data, as long as the data is small enough. In this story, the peripheral is 
performing the role of a "broadcaster" while the central would be performing the role of 

n "observer". When working in this mode, do realize that the data is flowing in only 
one direction ... from the publisher to the observer. If you need to send response back, 
you will need to form a connection. 


The rate of advertizing can be set to be a period between 20ms and 10.24seconds in 
steps of 0.625ms. Thus we can transmit our advertizing packets frequently or slowly. 


See also: 


ABLE Advertising Primer 





GAP Advertizing data 

There is theory and there is practice and studying BLE gives us the opportunity for both. 
Let us focus on the notion of a BLE peripheral broadcasting advertizing messages. Ata 
high level it will look like: 


«) 


Peripheral Central 





The advertized data payload has a maximum size of 31 bytes. Each payload is 
composed of one or more data structures where the format of each structure is: 





Length Advertising Data Type Data ... 

















The Length is 1 byte in size and indicates how many bytes, following the length byte, 
this record will be. The number of records in a payload is variable but, of course, the 
total amount of data has to be 31 bytes or less. Either a length of 0 or an ignorable 
structure type can be used. 


Here is an example of a real payload that | received: 


020105020A000319C1030302E0FF11094D4C452D3135202020202020202020 





Now we can parse this as follows: 
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02 01 05 —advertising type 0x01 

02 0a 00 — advertising type Ox0A 

03 19 cl 03—advertising type 0x19 

03 02 e0 ££ — advertising type 0x02 

11 09 4d 4c 45 2d 31 35 20 20 20 20 20 20 20 20 20 —advertising type 09 


Here is a simple routine that will step through the structures ... 


while(!finished) { 
length = *payload; 
payload++; 
if (length != 0) { 
ad_type = *payload; 
payload += length; 











ESP_LOGD(tag, "Type: 0x%.2x, length: %d", ad_type, length) ; 
} 
sizeConsumed += 1 + length; 
if (sizeConsumed >=31 || length == 0) { 


finished = 1; 
} 
} // !finished 
Now that we know how to see the structures and access them, the obvious question is 
what do each of the structures "mean". For most, they are architected in the BLE 
specification. Each structure (after the length) has a single byte that is the "advertising 
data type". These single byte number codes are described here: 


https:/Awww.bluetooth.com/specifications/assigned-numbers/generic-access-profile 
In our ESP32 environment, we have constant definitions for each: 





* ESP BLE AD TYPE FLAG (0x01) — The advert contains a byte of flags that are 
defined as following: 


o Bit O —LE Limited Discoverable Mode 

















o Bit 1— LE General Discoverable Mode 

o Bit 2—BR/EDR is NOT supported. 

o Bit 3 — Indicates whether LE and BR/EDR Controller operates simultaneously 
o Bit 4 — Indicates whether LE and BR/EDR Host operates simultaneously 

°o Bits 5-7 — Reserved. 





* ESP BLE AD TYPE 16SRV PART (0x02) —Incomplete list of 16bit service class 
UUIDs. 
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- ESP_BLE_AD TYPE_16SRV_CMPL (0x03) 
- ESP_BLE_AD TYPE_32SRV_PART (0x04) 
- ESP_BLE_AD TYPE_32SRV_CMPL (0x05) 


* ESP BLE AD TYPE 128SRV_PART (0x06) —Incomplete list of 16bit service class 
UUIDs. 


- ESP BLE_AD TYPE_128SRV_CMPL (x07) 


* ESP BLE AD TYPE NAME SHORT (0x08) — Shortened local name. 



























































* ESP BLE AD TYPE NAME CMPL (0x09) — Complete local name. 
¢ ESP _BLE_AD_TYPE_TX_PWR (0x0A) 

¢ ESP _BLE_AD_TYPE_DEV_CLASS (0x0D) 

¢ ESP _BLE_AD_TYPE_SM_TK (0x10) 

¢ ESP _BLE_AD_TYPE_SM_OOB_FLAG (0x11) 

¢ ESP _BLE_AD_TYPE_INT_RANGE (0x12) 

¢ ESP _BLE_AD_TYPE_SOL_SRV_UUID (0x14) 

¢ ESP_BLE_AD_TYPE_128SOL_SRV_UUID (0x15) 
¢ ESP_BLE_AD_TYPE_SERVICE_DATA (0x16) 

¢ ESP _BLE_AD_TYPE_PUBLIC_TARGET (0x17) 

¢ ESP_BLE_AD_TYPE_RANDOM_TARGET (0x18) 


« ESP_BLE_AD_TYPE_APPEARANCE (0x19) - It is likely this conforms to the 
assigned numbers found here 


https:/Awww.bluetooth.com/specifications/gatt/viewer? 
attributeXmIFile=org.bluetooth.characteristic.gap.appearance.xml and 


- ESP _BLE_AD_TYPE_ADV_INT (0x1A) 

- ESP _BLE_AD TYPE_32SOL_SRV_UUID (0x1B) 
- ESP _BLE_AD_TYPE_32SERVICE_DATA (0x1C) 
- ESP _BLE_AD_TYPE_128SERVICE_DATA (0x1D) 




















* ESP BLE AD MANUFACTURER SPECIFIC TYPE (0xFF) — Custom payload. 























With this in mind, if we look at our sample data ... we can see that it means: 
02 01 05 —advertising type 0x01 — ESP_BLE_AD_TYPE_FLAG 
02 0a 00 —advertising type OxOA —ESP_BLE_AD_ TYPE_TX_PWR 


Page 166 


03 19 cl 03—advertising type 0x19 - ESP_BLE_AD_TYPE_APPEARANCE 
03 02 ed ££ — advertising type 0x02 —-ESP_BLE_AD_TYPE_16SRV_PART 


11 09 4d 4c 45 2d 31 35 20 20 20 20 20 20 20 20 20 —advertising type 0x09 — 
ESP_BLE_AD_TYPE_NAME_CMPL 


Now we can consult the specification and determine what the data part of each 
advertising type means and we have our information. 


Because examining the advertising data of a GAP message is so important and so 
common, the ESP-IDF contains a very useful utility function that takes as an input the 
advertisement data and looks for an advertising type structure within it of a defined type. 
The function is called esp ble resolv_adv_data(). 


See also: 


esp_ble_resolve_adv_data 





Advertizability - limited and general 

Is "advertizability" even a real word? | think not ... but it describes what we want to 
cover. When we have a bluetooth peripheral, we somehow need to make it available to 
be discovered by a bluetooth central in order for the central to make requests of the 
peripheral. The way we achieve this is by making the peripheral visible by it 
broadcasting its advertising packets. When a peripheral starts advertising, it can tag the 
advert as either limited-discoverable or general-discoverable. The notion here is that 
limited-discoverable devices have "recently" been enable to start broadcasting while 
"general-discoverable" devices usually broadcast continuously. So what you may ask? 
Well, think of a user looking for a device. It is not uncommon for a new device to be 
added by pressing some button on it to start it broadcasting so that it can be found and 
paired. We want this new device to show up higher in the list of found devices than 
others ... and this can be achieved by recognizing that a device which only broadcasts 
for a limited period of time will enable its "limited-discoverable" flag and provide a hint to 
the software running on the central that the device is likely going to be the one the user 
is looking for. 


Now we have introduced the concept of an advertizing packet having two flags called 
"limited-discoverable" and "general-discoverable", only one of which may be set at a 
time. This leaves one more choice which is that neither "limited-discoverable" nor 
"general-discoverable" are set. This is an allowed transmission and the packet will still 
be detected by the observer however this indicates that no connection should be 
attempted and that the peripheral should not be listed to the user. 
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Filtering devices 
When we are looking for a device, we may find more devices than we want. Rather 


than present all devices to the user, we can choose to filter the set of available devices 
and hide the ones that we believe are of no interest. For example, if | am running a 
heart-rate monitor application on my phone, I'm really only interested in devices that can 
provide such information. My latest bluetooth headset or the outside temperature is not 
what I'm looking for. What we want to do is filter the set of ALL found devices down to 
only the ones that match some criteria of interest to us. In order for that to happen, 
each device must not only advertize its existence, but also supply information that can 
be used to include or eliminate it from selection. 


Performing a scan 

There isn't much value in generating advertising data if no-one is listening. In BLE the 
act of listening for advertising data is called "scanning". To perform a scan in the ESP32 
we perform the following tasks: 


1. We register a callback function to handle the received data. 
2. We define the parameters for how we would like the scan to be performed. 
3. We ask the ESP32 to start scanning. 


Translating these into ESP32 APIs we have esp ble gap register callback() to 
register our callback function to be invoked when a data arrives. 


We have the esp ble gap set scan params() to setup how we wish the scanning to be 
performed. 





We have esp ble gap start scanning() to initiate a scan request. 





If we need to interrupt our scanning before the specified duration of scanning has 
completed, we can Call esp ble gap stop scanning(). 





The function registered when we call esp ble gap register callback() is where the 
majority of our function will happen. The parameter to this function is itself a C function 
which the following signature: 


void gap_event_handler(esp gap ble cb event_t event, esp ble gap_cbh param_t *param) 











The param is a union of structures. 
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Event Type Data Property 

ESP _ GAP BLE ADV DATA SET COMPLETE EVT adv_data_cmpl 
ESP_GAP BLE ADV_ DATA RAW SET COMPLETE EVT adv_data_ raw_cmpl 
ESP _ GAP BLE ADV_START COMPLETE EVT adv_start_cmpl 
ESP_GAP BLE SCAN PARAM SET COMPLETE EVT scan_param_cmpl 

ESP_ GAP BLE SCAN RESULT _EVT scan_rst 

ESP_GAP BLE SCAN RSP_DATA RAW SET COMPLETE EVT scan rsp data_raw_cmpl 
ESP_GAP BLE SCAN RSP DATA SET COMPLETE EVT scan_rsp_data_cmpl 
ESP_ GAP BLE SCAN START COMPLETE EVT scan_start_cmpl 











The event parameter defines the type of event we have received. Event types include: 





* ESP GAP BLE ADV DATA RAW SET COMPLETE EVT— Raw advertizing data operation 























complete. 




















* ESP GAP BLE ADV DATA SET COMPLETE EVT— Called when advertizing data set is 














complete. Structure parameter is called scan rsp data_cmpl. 





© esp bt status t status — The status of the event. 














* ESP GAP BLE ADV START COMPLETE EvtT — Called when advertizing scan startup is 

















complete. The parameter is a property called scan start _cmp1 which contains: 


° esp bt status _t status — The status of the event. 











* ESP GAP BLE SCAN PARAM SET COMPLETE EVT — Called when scan parameters set 




















complete. Structure parameter is called scan param cmpl. 


° esp _bt_status_t status 








* ESP GAP BLE SCAN RESULT EvT-— The param is an instance of 




















esp ble gap cb param t. Called when one scan result is ready. The structure 





parameter is called scan rst. 


© esp gap search evt_t search evt — Choices are: 





ESP GAP SEARCH INQ RES EVT — We have received a search result. 




















ESP GAP SEARCH INQ CMPL EvT — The search is complete. 
ESP_GAP_SEARCH_DISC_RES_EVT 
ESP_GAP_SEARCH_DISC_BLE_RES_EVT 
ESP_GAP_SEARCH_DISC_CMPL_EVT 
ESP_GAP_SEARCH_DI_DISC_CMPL_EVT 
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=» ESP _GAP_SEARCH_SEARCH_CANCEL_CMPL_EVT 

esp bd addr t bda— The address of the device. 6 bytes of data. 
esp bt dev type t dev type — One of: 

» ESP_BT_DEVICE_TYPE_BREDR 

» ESP_BT_DEVICE_TYPE_BLE 

» ESP_BT_DEVICE_TYPE_DUMO 








esp ble addr type t ble addr type — One of 
» BLE _ADDR_TYPE_PUBLIC 

» BLE ADDR_TYPE_RANDOM 

» BLE _ADDR_TYPE_RPA_PUBLIC 

» BLE _ADDR_TYPE_RPA_RANDOM 





esp ble evt type t ble evt type — One of 





int rssi — The signal strength. 

















uint8 t ble adv[ESP BLE ADV DATA LEN Max] — The advertized data. 





int flag 


int num_resps — The number of responses received. This is valid when the 
search evt type iS ESP GAP SEARCH INQ CMPL EVT. 











* ESP_GAP_BLE_SCAN_RSP_DATA_RAW_SET_COMPLETE_EVT — ???. 





* ESP GAP BLE SCAN RSP DATA SET COMPLETE EVT — Called when the scan 
response data set is complete. Structure parameter is called: 


scan rsp data _cmpl. 





(e) 























esp_bt_status_t status 


- ESP_GAP_BLE_SCAN_START_COMPLETE_EVT — 277. 


A typical series of events received might be: 











° ESP GAP BLE SCAN PARAM SET COMPLETE EVT 























° ESP GAP BLE SCAN START COMPLETE EVT 






































° ESP GAP BLE SCAN RESULT EVT— ESP GAP SEARCH INQ RES EVT 





























° ESP GAP BLE SCAN RESULT EVT— ESP GAP SEARCH INQ CMPL EVT 





See also: 
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esp_ble_gap_register_callback 
esp_ble_gap_set_scan_params 
esp_ble_gap_start_scanning 
esp_ble_gap_stop_scanning 


Performing advertising 
If our ESP32 is going to be a peripheral, then it will be advertising its existence. The 
ESP-IDF provides some APIs to achieve that task. At a high level: 





1. Callesp ble gap config adv data() to specify the content of our periodic 
advertisement. 





2. Callesp ble gap start advertising() to initiate the periodic advertisement. 





While superficially simple, we need to consider all the distinct parameters that are 
available to us ... and there are many. 


We will start with the esp ble gap config adv_data(). This is where we specify the 
content of the advertisement payload. An example structure would be: 


static esp ble adv data t test adv data = { 








.set_scan_rsp = false, 
-include_name = true, 
.include_txpower = true, 
-min_interval = 0x20, 

-max interval = 0x40, 
.appearance = 0x00, 
-manufacturer len = 0, 
-p_manufacturer data = NULL, 
.service data_len = 0, 


-p_service data = NULL, 

.service uuid_len = 32, 

-p_service _uuid = test _service uuidl128, 
-flag = 0x2, 





}; 

Once we have started advertising, we can check the published information using: 
S$ sudo hcitool lescan 

See also: 


esp_ble_gap_config_adv_data 
esp_ble_gap_start_advertising 
esp_ble_gap_stop_advertising 
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Bluetooth GATT 

The Generic Attribute Protocol (strangely called GATT) provides a mechanism for 
passing data in a standard form. GATT is always present in BLE. Think of GATT asa 
way to send and receive data that is "remembered" at the GATT server (while it is 
running). Aclient can request the values of data items as well as receive asynchronous 
notifications as events when something interesting happens at the GATT server. 


At the high level of the protocol there is the concept of a service. The service is the 
grouping of functionally related attributes. Within a service are characteristics where a 
characteristic is a property of that service. Each characteristic type is identified by its 
own UUID value. In addition a characteristic contains a value, properties, security and 
may also include descriptors. 





Profile 





Service 


rc 


be EI 


——- 





——— 








Characteristic 





Properties 























Characteristic 












































Within the specification of GATT we have the notion of two roles ... namely that of a 
client and that of a server. A GATT server is commonly a passive entity that waits for 
requests from GATT clients and services them as they arrive. 


When a GATT client starts, it assumes little about the GATT server and first performs an 
inquiry upon the server to determine its characteristics. 


Every BLE device must include the capability to be a GATT server. 


The GATT server manages attributes that can be read by or written from a GATT client. 
How these attributes are stored by the GATT server internally is not defined in the 
specification and left to the implementers to choose. 


Within a GATT server, every attribute has a unique "handle" that is 16 bits in length. 
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The value of an attribute is governed by its data type which is defined by a UUID. It has 
a maximum length of 512 bytes. 


An attribute also has permissions which govern what one can do against an attribute. 
The permissions include: 


« None 
« Readable 
¢ Writable 


¢ Both readable and writable 


This story of raw attributes is further specified in the GATT protocol by the notion of 
services and characteristics. 


Think of a service a logical description that a GATT server is prepared to do something 
that is well defined. If it claims to provide a service, then it must adhere to the contract 
described by that service. This contract is defined by a set of characteristics and the set 
of those make up the service. 


See also: 


Generic Attribute Profile (GATT) 

generic attributes (gatt) and the generic attribute profile 
GATT-Based specifications 

GATT services — Assigned numbers 

GATT delarations — Assigned number 

GATT characteristics - Assigned numbers 

gatttool 














Being a GATT client 
From the ESP32 perspective, to be a GATT client we perform: 





1. Register a callback to receive GATT events using 
esp ble gattc_ register callback(). 


2. Callesp ble gattc app register() to register this application. 





3. Open a connection to the GATT server using esp ble gattc_open(). 


4. When an open event arrives, execute a search using 


esp ble gattc_ search service(). 


When we call esp_ble_gattc_open() we are requesting to open a GATT connection to a 
specific device. This request is non-blocking and will execute in the background. 
Eventually we will receive a GATT event indicating the outcome. The event type will be 
ESP GATTC OPEN EVT. 
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Client ESP-IDF <Radio> Device 


esp_ble_gattc_open 
— 
oo 
ee 


GATT Event ——————— 
ESP_GATTC_OPEN_EVT 





As part of the response data from the Esp _GATTC OPEN EVvT we will receive a connection 


identifier (conn_id). This conn_id can be loosely thought of as a socket to the partner 
device. 

















Once we have formed a connection to the partner device, we can ask it about the 
services that it offers. We do this by calling esp ble gattc_search_service() function. 
Like other BLE mechanisms, this is an asynchronous operation that results in a series 
of GATT events being generated. For each service possessed by the device, an 
ESP_GATTC_ SEARCH _RES_EVT Is fired and finally, when we have seen all the services, we 
get an ESP_GATTC_ SEARCH CMPL EVT. This is illustrated in the following diagram: 

Client ESP-IDF <Radio> Device 





























esp_ble_gattc_search_service 


— 


GATT Event ee 
ESP_GATTC_SEARCH_ARES EVT 
+ 


GATT Event SO Sr 
ESP_GATTC_SEARCH_AES EVT 
£-_ 9 el" 


GATT Event — 
ESP_GATTC_SEARCH_CMPL_EVT 
oo"... 


For each of the services we get back we can start to invoke those services on the 
device. 


See also: 


esp_ble_gattc_register_callback 
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esp_ble_gattc_app_register 
esp_ble_gattc_open 
esp_ble_gattc_search_service 
GATT Services 


Being a GATT Server 
The high level of being a GATT server is: 


esp bt_controller init () 

esp_bt_ controller enable() 

esp bluedroid init () 

esp _bluedroid enable () 

esp ble gatts_ register callback () 





sp ble gap register callback () 
esp ble gatts app register () 





The call to esp ble gatts app register() registers our application. This passes 
control back to the BLE subsystem and, when ready, will call back the GATT server 
event handler with an event type of esp _catts REG EvT. When we receive that, we then 
do the next part of the setup: 




















esp ble gap set device name () 
esp ble gap config adv data() 
esp ble gatts create service () 











To test that all is working, we can run the hcitool from a Linux system: 


S$ sudo hcitool lescan 
24:0A:C4:00:00:96 MYDEVICE 














See also: 


esp_ble_gatts_register_callback 
esp_ble_gap_register_callback 
esp_ble_gap_set_device_name 
esp_ble_gap_config_adv_data 
esp_ble_gatts_app_register 
esp_ble_gatts_create_service 


Service Discovery Protocol 

When a client application wishes to request that a connection be established, the client 
needs to know the port number on which the server is listening. In TCP/IP land, this is 
achieved by having the client and the server share the implicit knowledge of the port 
number to use. In Bluetooth, extra functions have been made available. Specifically, 
there is a service available called the Service Discovery Protocol or "SDP". At the 
server, when a service is offered, the port number of that service is registered to the 
local SDP. When a client now wishes to use the target service, it first requests endpoint 
information from the SDP running on the server. The SDP returns the endpoint 
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information and the client now has all the information it needs to create a direct 
connection to the desired target service. The unit of information managed by the SDP 
server is called a "service record" or "SDP record". 


Acommand line interface tool called sdptool is available to examine a Bluetooth 
device's SDP data. A simple command is: 


$ sdptool browse <Bluetooth Address> 
This returns a series of records of the form: 
¢ Service Name 
* Service Description 
¢ Service Provider 
¢ Service RecHandler 
¢ Service Class ID List 
¢ Protocol Descriptor List 
¢ Profile Descriptor List 
¢ Language Base Attr List 
See also: 


man(1) — sdptool 


ESP32 and Bluetooth 
Logic appears to be: 


esp bt_controller init() 
esp bt controller enable (ESP BT MODE BTDM) 
esp bluedroid init () 








esp bluedroid enable () 





sp ble gap register callback () 
esp ble gattc_register callback () 
esp ble gattc app register () 

sp ble gap set scan params () 
esp ble gap start scanning (20) 

















Debugging ESP32 Bluetooth 

The ESP32 bluetooth implementation is built upon an environment called Bluedroid. 
The reason this becomes important is that for full understanding of the the ESP32 
Bluetooth environment, we need to understand the Bluedroid environment as well. For 
example, the art of getting lower level diagnostics drops us down to the Bluedroid APIs. 
For example: 
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#include <gatt_api.h> // bluedroid include 


GATT SetTraceLevel (6) ; 


will switch on GATT level tracing. 


Bluetooth C Programming in Linux 
Within the C / Linux environment we have an implementation of the API stack called 
"BlueZ". The BlueZ implementation supports RFCOMM, L2CAP, SCO and HCI. 


In order to perform Bluetooth programming we must install the package called 
"libbluetooth-dev" using: 

S$ sudo apt-get install libbluetooth-dev 

When compiling, we need to link with libbluetooth. 

See also: 


An Introduction to Bluetooth Programming 





hci_get_route 
Retrieve a handle to the specified Bluetooth device or the first available if NULL is 
supplied. 


int hci_get_route(bdaddr_t *bdaddr) 


hci_open_dev 
Open the specified device and get a handle to that device. The returned value is a 
socket. 


int hci_open_dev(int dev_id) 


If the return is -1 then an error was encountered and the details of the error can be 
found in errno. 


hci_inquiry 


int hcei_inquiry ( 
int dev_id, 
int len, 
int max_rsp, 
const uint8 t *lap, 
inquiry info **ii, 
long flags) 


where: 
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* dev _id—the device id of the adapter as retruned by hci_get_route. 

* len —The duration of the scan * 1.28 seconds. 

* max rsp — The maximum number of responses we are willing to accept. 
* lap —may be NULL 


¢ ii-— Pointer to an array of inquiry_info structures to be populated. The storage 
must exist and be at least of size max rsp * sizeof (inquiry info). 





e flags 
°  ¢—Cached results allowed 


© TREQ CACHE FLUSH —Any cached values are discarded and only new 
responses will be used. 








The inquiry_info is a struct containing: 
¢ bdaddr_t bdaddr 
* uint8 tpscan_rep_mode 
¢ uint8 t pscan_period_mode 
¢ uint8_t pscan_mode 


¢ uint8_tdev_class[3] — The device class is encoded in the assigned numbers — 
baseband. 


¢ uint16_t clock_offset 


See also: 


Assigned numbers — baseband 





hci_read_remote_name 
Retrieve the display name of a specified device. 


int hci_read_remote_name ( 
int hci_sock, 
const baddr_t *addr, 
int len, 
char *name, 
int timeout 


* len —the size of the name buffer to hold the display name. 


* name —a buffer to hold the display name. 
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* timeout — Maximum number of milliseconds to wait before giving up. 


On return, a value of 0 indicates success. 


str2ba 
Convert a string representation of a Bluetooth address into an address. 


str2ba(const char *str, bdaddr_t *ba) 


Where str is the string representation of the Bluetooth address and ba is a pointer to a 
bdaddr_t Structure to hold the resulting address. 


ba2str 

Convert a Bluetooth address to a string. The string buffer must be at least 18 bytes 
long. 

ba2str (const bdaddr_t *ba, char *str) 

The ba is a pointer to a bdaddr_t structure while str is the buffer to be populated with 
the string representation. 


sdp_connect() 
sdp_service_search_attr_req() 


sdp_record_register() 


Bluetooth Audio 

Bluetooth speakers and headphones are common so a natural question would be how 
to get sound out of them from the Pi. The answer is to install an application called 
PulseAudio. 


S$ sudo apt-get install pulseaudio pulseaudio-module-bluetooth 


The Bluetooth profile we want to work with is called A2ZDP (Advanced Audio Distribution 
Profile). 


Bluetooth RFCOMM 
A serial protocol is available via Bluetooth and is called "RFCOMM" for "Radio 
Frequency Communication". 
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When programming with C, we want to create a socket using: 








int s = socket (AF BLUETOOTH, SOCK STREAM, BTPROTO_RFCOMM) ; 


A socket address structure for Bluetooth RFCOMM is a struct called sockaddr_re which 


contains: 


° sa_family rc_ family — This will always be AF BLUI 





E TOOTH. 


* bdaddr_ t rc _bdaddr — The address of the device to which we wish to connect or 
listen upon. If any local Bluetooth adapter will suffice when we are a server, we 


can supply BDADDR_ ANY. 


* uint8 t rc channel — The channel to which we wish to connect. 


To be a client of an RFCOMM server, we would use: 


#include <stdio.h> 

#include <unistd.h> 

#include <sys/socket.h> 

#include <bluetooth/bluetooth.h> 
#include <bluetooth/rfcomm.h> 


int main(int argc, char *argv[]) 
{ 
if (argc != 2) { 
printf ("Usage: %s bdaddr\n", argv[0]); 
return 0; 


} 


struct sockaddr re addr = {0}; 
int s, status; 
char *dest = argv[1]; 








s = socket (AF BLUETOOTH, SOCK STREAM, BTPROTO RFCOMM) ; 


addr.rc_ family = AF BLUETOOTH; 
addr.rc_channel = 1; 
str2ba(dest, &addr.rc_ bdaddr) ; 





status = connect(s, (struct sockaddr *)é&éaddr, sizeof(addr )); 
if(status == 0) { 
status = send(s, "hello!", 6, 0); 


} 


if(status < 0) { 
perror ("connect"); 


} 


close(s); 
return 0; 
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while to be a server we would use: 


#include <stdio.h> 

#include <unistd.h> 

#include <sys/socket.h> 

#include <bluetooth/bluetooth.h> 
#include <bluetooth/rfcomm.h> 


int main(int argc, char **argv) 


{ 


} 


struct sockaddr _ rc loc_addr = { 0 }, rem _addr = { 0 }; 
char buf[1024] = { 0 }; 

int s, client, bytes read; 

socklen t opt = sizeof (rem_addr); 


// allocate socke 
s = socket (AF BLUETOOTH, SOCK_STREAM, BTPROTO_ RFCOMM) ; 


ct 








// bind socket to port 1 of the first available 

// local bluetooth adapter 

loc_addr.rc_ family = AF BLUETOOTH; 

loc_addr.rc_bdaddr = *BDADDR_ ANY; 

loc_addr.rc_ channel = (uint8 t) 1; 

bind(s, (struct sockaddr *)&loc_addr, sizeof(loc_addr)); 





// put socket into listening mode 
listen(s, 1); 


// accept one connection 
client = accept(s, (struct sockaddr *)&rem_addr, &opt); 


ba2str(&rem_addr.rc_bdaddr, buf); 
fprintf(stderr, "accepted connection from $s\n", buf); 
memset (buf, 0, sizeof (buf)); 


// vead data from the client 
bytes read = read(client, buf, sizeof(buf)); 
if (bytes read > 0) { 

printf ("received [%s]\n", buf); 





// close connection 
close(client) ; 
close(s); 

return 0; 


See also: 


RECOMM with TS 07.10 
man(1) — rfcomm 


An Introduction to Bluetooth Programming 
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Bluetooth tools 


(2ping 

In TCP/IP networking, we have a tool called ping which sends an ICMP packet over the 
network to which the partner responds. We can use this command to determine the 
"liveness" of the partner as well as get the round trip response times. For Bluetooth, we 
have a similar tool called "12ping". This command sends a L2CAP echo request to the 
partner and waits for the response. 


At the highest level, we use: 


$ sudo 12ping <bd_addr> 


where bd_addr is the address of the target device. Here is an example output: 


S sudo 12ping 00:1A:7D:DA:71:13 

Ping: 00:1A:7D:DA:71:13 from B8:27:EB:62:03:9F (data size 44) ... 
44 bytes from 00:1A:7D:DA:71:13 id 0 time 11.32ms 

44 bytes from 00:1A:7D:DA:71:13 id 1 time 66.06ms 

44 bytes from 00:1A:7D:DA:71:13 id 2 time 19.84ms 

44 bytes from 00:1A:7D:DA:71:13 id 3 time 52.38ms 





As of 05/2016, running the 12ping command on current Raspbian ends after about 5 
seconds of pinging with a message: 

Send failed: Connection reset by peer 

Current thinking is that this is caused by a deliberate kernel timeout of L2CAP requests 
that don't result in a connection. The theory believed to be that to save battery life in 


real Bluetooth devices, if a connection isn't established in the timeout period, don't 
bother to keep trying and, presumably, waste power resources. 


The I2ping command is delivered as part of the "bluez" package. 


See also: 
man(1) — I2ping 

rfcomm 

See also: 


man(1) — rfcomm 


bluetoothctl 
One of the primary tools for working with Bluetooth is called bluetoothctl. Oddly, this 
command seems to have only the bare bones of a man page (shame). 


One should run bluetoothct1 as root using: 


S$ sudo bluetoothctl 
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If you fail to run it as root, it will just silently sit there until you interrupt it. This command 
line tool has the following commands: 


* list —List available controllers 

* show [ctrl] — Controller information 

* select <ctri1>-— Select default controller 

* devices — List available devices 

* paired-devices — List paired devices 

* power <on/off>-— Set controller power 

* pairable <on/off>-— Set controller pairable mode 
* discoverable <on/off>— Set controller discoverable mode 
* agent <on/off/capability>— Enable/disable agent with given capability 
* default-agent — Set agent as the default one 

* scan <on/off>— Scan for devices 

* info <dev>— Device information 

* pair <dev>— Pair with device 

* trust <dev>— Trust device 

* untrust <dev>— Untrust device 

* block <dev>— Block device 

* unblock <dev> — Unblock device 

* remove <dev> — Remove device 

* connect <dev>— Connect device 

* disconnect <dev>— Disconnect device 

* version — Display version 

* quit — Quit program 


See also: 


hciconfig 
As mentioned, HCI is the "Host-Controller Interface" which is the layer of 
communication between the higher level protocols of bluetooth and the bluetooth lower 
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level controller. The "hciconfig" command allows us to execute commands through 
this logical interface. 


Running hciconfig by itself will list all the bluetooth devices found on the computer: 


S$ hciconfig 
hci0d: Type: BR/EDR Bus: UART 
BD Address: B8:27:EB:62:03:9F ACL MTU: 1021:8 SCO MTU: 64:1 
UP RUNNING PSCAN 
RX bytes:19100 acl:150 sco:0 events:457 errors:0 
TX bytes:7952 acl:150 sco:0 commands:184 errors:0 








Each bluetooth device has a logical identifier of the form "hcix" where the devices are 
numbered 0, 1, 2 ... etc. 


To refer to a specific device, most of the commands that we issue through hciconfig 
will take the hcix device identifier to target the correct instance. 


Some of the more interesting commands we can perform with hciconfig include: 
* Getting and setting the devices display name property 
¢ Enabling/disabling page support 
¢ Enabling/disabling scan inquiry support 

The hciconfig command is supplied as part of the "bluez" package. 

Some useful commands include: 


Start LE broadcasting connectable undirected advertising 


S$ sudo hciconfig hci0 leadv 0 


Start LE broadcasting non-connectable undirected advertising 


S$ sudo hciconfig hcid0 leadv 3 


Stop LE broadcasting 


S$ sudo hciconfig hci0 noleadv 


See also: 


hcitool 
man(8) — hciconfig 


hcidump 
This tool is installed through: 


S$ sudo apt-get install bluez-hcidump 


The tool appears to dump the commands sent through the host/controller interface. 
Try running with: 


$ sudo hcidump -x -R 
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to see low-level data. 


hcitool 
The hcitool Is delivered as part of the "bluez" package on Linux. 


We can issue raw commands through the HCI using: 
hcitool cmd <OGF> <OCF> 


Where the combination of the two bytes <OGF> and <OCF> define the command to 
run. For LE controller commands, the <OGF> is 0x08. 


To scan for bluetooth LE devices, use: 

S$ sudo hcitool lescan 

We can start advertising packets. See BT Spec 4.2 Vol 2, Part E 7.8.7 
Using: 


$ sudo hcitool cmd 0x08 0x0008 <Length> <Content> 
S$ hciconfig hci0 leadv 0 


See also: 
man(1) — hcitool 


hciconfig 





gatttool 

Interact with a BLE device at the GATT level. In order to interact with a BLE device at 
the gatt level, we need its device address. Using "hictool lescan" is a good way to get 
the address. Typically the program is run with: 


S$ sudo gatttool --device=<Address> --interactive 


This will return a command prompt that starts with the partner device address: 


[FF:FF:45:19:14:80] [LE]> 





The sub-commands available to us include: 


connect [address [address type] ] Connect to a remote device 
disconnect Disconnect from a remote device 
primary [UUID] Primary Service Discovery 
included [start hnd [end hnd] ] Find Included Services 
characteristics [start hnd [end hnd [UUID]]] Characteristics Discovery 
char-desc [start hnd] [end hnd] Characteristics Descriptor Discovery 
char-read-hnd <handle> Characteristics Value/Descriptor Read 
by 

handle 
char-read-uuid <UUID> [start hnd] [end hnd] Characteristics Value/Descriptor Read 
by UUID 
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char-write-req 
Request) 
char-write-cmd 
response) 
sec-level 

mtu 


<handle> <new value> 


<handle> <new value> 


[low | medium | high] 
<value> 





Characteristic Value Write (Writ 


Characteristic Value Write (No 


Set security level. Default: low 





Exchange MTU for GATT/ATT 


Once connected, we can interrogate the device about its primary function by running the 
"orimary" Command: 


[FF:FF:45:19:14: 
attr handle: 0x0001, end grp handle: 
attr handle: 0x0006, end grp handle: 
attr handle: 0x0009, end grp handle: 
attr handle: 0x000c, end grp handle: 





80] [LE]> primary 


0x0005 uuid: 
0x0008 uuid: 
0x000b uuid: 
0x000e uuid: 


00001800-0000-1000-8000-00805£f9b34fb 
0000180£-0000-1000-8000-00805f9b34fb 
00001802-0000-1000-8000-00805f9b34fb 
0000£ffe0-0000-1000-8000-00805f9b34fb 


Notice specifically the UUIDs. These correspond to the assigned numbers of the GATT 
specifications. Contrast this with the output of "bluetoothctl info" which shows the 


following: 


[bluetooth] # info FF:FF:45:19:14:80 


Device FF:FF:45: 


19:14:80 


Alias: FF-FF-45-19-14-80 
Appearance: 0x03cl 


Icon: input-keyboard 


Paired: no 


Trusted: 
Blocked: 


no 
no 


Connected: yes 


LegacyPairing: no 


UUID: Generic Access Profile 
UUID: Immediate Alert 

UUID: Battery Service 

UUID: Unknown 


( 
( 
( 
( 


00001800-0000-1000-8000-00805£f9b34fb) 
00001802-0000-1000-8000-00805£9b34 fb) 
0000180f-0000-1000-8000-00805£f9b34 fb) 
0000ffe0-0000-1000-8000-00805f9b34 fb) 


For example, Ox...1802... is the Immediate Alert service. 


Looking back at the gatttoo1 output, for each of the services, we see a "handle range". 


This describes the handles to the characteristics offered by that service. From the 
handles, we can ask the device what characteristics these represent: 


[FF:FF:45:19:14: 


handle: 0x0009, 
handle: 0x000a, 
handle: 0x000b, 


The UUIDs of the declarations and characteristics can then be examine in the assigned- 


numbers lists. 


For example 





80] [LE]> char-desc 0x0009 0x000b 


uuid: 
uuid: 
uuid: 


00002800-0000-1000-8000-00805f9b34fb 
00002803-0000-1000-8000-00805f9b34fb 
00002a06-0000-1000-8000-00805f9b34fb 


¢ Ox...2800...— GATT Primary Service Declaration 
¢ 0x...2803 ... — GATT Characteristic Declaration 
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e O0x...2A06... — Alert Level 


See also: 


Bluetooth GATT 
man(1) — gatttool 


Bluetooth examples 


The iTag peripheral 

The iTag is a cheap little thingy ($2-$4 on eBay) that is a bluetooth device. Its purpose 
is to form a connection with a bluetooth master. If the connection is subsequently lost, 
the device starts beeping. In addition, the device can receive a "ping" from the master 
to instruct it to immediately start beeping. In all these cases, it acts as a useful device 
to help you locate it should it get lost. Now imagine connecting it to your keys, pet, kid 
or other loose-able thing and now we have a potential of either being notified that it is 
out of range or else it will beep to say "help me". 





This makes a great device for testing the ESP32's ability to work as a BLE master. 


If we run a BLE scan and listen for advertising packets, we will find that it shows up. 
From there we can get its bluetooth address. For example, when | ran an ESP32 to 
look for devices, the ESP32 found my tag with the address "FF:FF:45:14:80". Once the 
ESP32 found the address, | was the able to issue an open request to it which 
succeeded. Once | had an open connection, | issued a search request upon it and four 
services were returned. These were: 


¢ UUID: 0x1800 
¢ UUID: 0x1802 
¢ UUID: 0x180f 
¢ UUID: Oxffed 
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Since these were 16bit UUIDs, that is the indication that they are specified by the 
bluetooth special interest group (SIG). Asearch at the GATT services web page found 
the first three: 


« UUID: 0x1800 — Generic Access 
¢ UUID: 0x1802 — Immediate Alert 





« UUID: 0x180f — Battery Service 


Great ... this is starting to make sense. Now we can drill down into the characteristics 
for each service. From the bluetooth specs, the characteristics possible are: 


« UUID: 0x1800 — Generic Access 
o UUID: 0x2a00 — Device Name 





o UUID: 0x2a01 —- Appearance 
o UUID: 0x2a02 — Peripheral Privacy Flag 
o UUID: 0x2a03 — Reconnection Address 








o UUID: 0x2a04 — Peripheral Preferred Connection Parameters 
¢ UUID: 0x1802 — Immediate Alert 


o UUID: 0x2a06 — Alert Level 
¢ UUID: 0x180f — Battery Service 





o UUID: 0x2a19 — Battery Level 


When we actually performed a characteristics query, what was returned were: 
¢ UUID: 0x1800 — Generic Access 
o UUID: 0x2a00 — Device Name 





o UUID: 0x2a01 — Appearance 
¢ UUID: 0x1802 — Immediate Alert 
o UUID: 0x2a06 — Alert Level 
¢ UUID: 0x180f — Battery Service 





o UUID: 0x2a19 — Battery Level 


Close enough to what we expected. 
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Smart Watch / The TW64 Band 
The TW64 watch/band can be found on eBay for about $9. Performing an eBay search 
using "TW64" will turn up many. 





TW64 














A 


We start by running a BLE scan: 





S$ sudo hcitool lescan 


Which came back with: 


LE Scan ... 
A4:C1:38:77:1A:19 KeepBand 
A4:C1:38:77:1A:19 (unknown) 





And now we know the device address. Of course, each instance will vary. 


next we can connect to the device and ask it about itself: 


S$ sudo gatttool --device=A4:C1:38:77:1A:19 --interactive 

> connect 

> primary 

attr handle: 0x0001, end grp handle: 0x0007 uuid: 00001800-0000-1000-8000-00805f9b34fb 
attr handle: 0x0008, end grp handle: 0x000b uuid: 00010203-0405-0607-0809-Oa0b0c0d1911 
attr handle: 0x000c, end grp handle: 0x0011 uuid: 66880000-0000-1000-8000-008012563489 


and similarly, we can also run: 


$ sudo bluetoothctl 

# info A4:C1:38:77:1A:19 

Device A4:C1:38:77:1A:19 
Name: KeepBand 
Alias: KeepBand 
Appearance: 0x0180 
Paired: no 
Trusted: no 
Blocked: no 
Connected: no 
LegacyPairing: no 
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UUID: Human Interface Device (00001812-0000-1000-8000-00805£f9b34 fb) 
UUID: Battery Service (0000180£-0000-1000-8000-00805f9b34 fb) 


Interestingly, notice the distinction in services offered. 


A search at the GATT services web page found: 
¢ UUID: 0x1800 — Generic Access 





¢ UUID: 0x180f — Battery Service 
¢ UUID: 0x1812 — Human Interface Device 


Again using gattool, we can ask for the description of characteristics: 


char-desc 







































































handle: 0x0001, uuid: 00002800-0000-1000-8000-00805f9b34fb 
handle: 0x0002, uuid: 00002803-0000-1000-8000-00805f9b34fb 
handle: 0x0003, uuid: 00002a00-0000-1000-8000-00805f9b34fb 
handle: 0x0004, uuid: 00002803-0000-1000-8000-00805f9b34fb 
handle: 0x0005, uuid: 00002a01-0000-1000-8000-00805f9b34fb 
handle: 0x0006, uuid: 00002803-0000-1000-8000-00805f9b34fb 
handle: 0x0007, uuid: 00002a04-0000-1000-8000-00805f9b34fb 
handle: 0x0008, uuid: 00002800-0000-1000-8000-00805f9b34fb 
handle: 0x0009, uuid: 00002803-0000-1000-8000-00805f9b34fb 
handle: 0x000a, uuid: 00010203-0405-0607-0809-0Oa0b0c0d2b12 
handle: 0x000b, uuid: 00002901-0000-1000-8000-00805f9b34fb 
handle: 0x000c, uuid: 00002800-0000-1000-8000-00805f9b34fb 
handle: 0x000d, uuid: 00002803-0000-1000-8000-00805f9b34fb 
handle: 0x000e, uuid: 66880001-0000-1000-8000-008012563489 
handle: 0x000f, uuid: 00002803-0000-1000-8000-00805f9b34fb 
handle: 0x0010, uuid: 66880002-0000-1000-8000-008012563489 
handle: 0x0011, uuid: 00002902-0000-1000-8000-00805f9b34fb 


Hardware interfacing 

When working with an ESP32 we will quickly recognize that it has a lot of capabilities for 
interacting with a variety of hardware devices. These may be through GPIO, SPI, I2C, 
Serial or other techniques. In this section we start to examine these distinct techniques 
and look at each one in turn. 


To interface your ESP32 to hardware, you will be delving down into the hardware levels 
and attaching devices to the pins of your ESP32. Since there are many modules 
available, you will want to become familiar with the specifics of the modules you are 
working with as physical pin locations may differ from one manufacturer to another. 


See also: 


Modules 
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GPIOs 

GPIO or General Purpose Input / Output is the ability to drive external pins of the 
ESP32 to a signal level of "1" or "0" under application control. We can also choose to 
read the signal level that may be present on the pin. 


When we think of a GPIO we must realize that at any one time, each pin instance has 
two operational modes. It can either be an input or an output. When it is an input, we 
can read a value from it and determine the logic level of the signal present at the 
physical pin. When it is an output, we can write a logic level to it and that will appear as 
a physical output. 


Another vital consideration when working with GPIOs is the voltage level. The ESP32 is 
a 3.3V device. You need to be extremely cautious if you are working with 5V (or above) 
partner MCUs or sensors. Unfortunately devices like the Arduino are typically 5V as are 
USB — UART converters and many sensors. This means you are as likely as not to be 
working in a mixed voltage environment. Under no circumstances should you think you 
can power or connect to the ESP32 with a direct voltage of more than 3.3V. Obviously, 
you can convert higher voltages down to 3.3V but never try and connect a greater 
voltage directly. Another subtler consideration is when using GPIOs for signal input and 
supply greater than 3.3V as a high signal value. | strongly suggest not doing that. 
Some folks may claim you can "get away with it" and if you experiment it may (seem) to 
work but you are taking an unnecessary risk for no obviously good reason. If it works ... 
then it will work till it doesn't at which point it will be too late and you may cook your 
device. 


Because accidents happen when building GPIO based circuits, | recommend buying 
more ESP32 instances than you need. That way if you do happen to find yourself 
needing a second (or third or fourth) you will have them at your disposal. 


To use the GPIO functions supplied by the ESP-IDF, we must include "driver/gpio.h". 


Next we must call gpio pad select gpio() to specify that the function of a given pin 
should be that of GPIO as opposed to some other function. 


There are 34 distinct GPIOs available on the ESP32. They are identified as: 
* GPIO_NUM_0—GPIO NUM 19 
* GPIO NUM _21—GPIO NUM 23 


* GPIO NUM 25—GPIO NUM 27 




















* GPIO NUM 32—GPIO NUM 39 


The ones that are omitted are 20, 24, 28, 29, 30 and 31. 
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Note that GPIo NUM 34—GPIO NUM 39 are input mode only. You can not use these pins 
for signal output. Also, pins 6, 7, 8, 9, 10 and 11 are used to interact with the SPI flash 
chip ... you can not use those for other purposes. 


The data type called gpio num _t is a C language enumeration with values 
corresponding to these names. It is recommended to use these values rather than 
attempt to use numeric values. 


When we want to use a GPIO we need to be cognizant of whether we are using it as a 
signal input or a signal output. Think of this as the direction setting. We can set the 
direction with a call to gpio set direction(). For example, to set a pin as output we 
might call: 


gpio_set_direction(GPIO_NUM_17, GPIO MODE OUTPUT); 





while to set it as input we might call: 


gpio_set_direction(GPIO_NUM_17, GPIO MODE INPUT); 





If we have set our GPIO as output, we can now set its signal value to be either 1 or 0. 
We do that by calling gpio set level(). 


Here is an example that toggles a GPIO on and off once a second: 


gpio_pad_select_gpio(GPIO NUM 17); 
gpio_set_direction(GPIO_NUM_17, GPIO MODE OUTPUT); 
while(1) { 

printf ("Off\n"); 

gpio_set_level(GPIO NUM 17, 0); 

vTaskDelay(1000 / portTICK_RATE MS); 








printf ("On\n") ; 
gpio_set_level(GPIO_NUM_17, 1); 
vTaskDelay(1000 / portTICK_RATE MS); 








} 
When we run this and examine the output on a logic analyzer, all is as desired: 





As an alternative to setting all the attributes of individual pins, we can set the attributes 
of one or more pins via a single call using the gpio_config() function. This takes a 
structure called gpio_config_t as input and sets the direction, pull up, pull down and 
interrupt settings of all the pins supplied in a bit mask. For example: 

gpio_config_ t gpioConfig; 


gpioConfig.pin bit_mask = (1 << 16) | (1 << 17); 
gpioConfig.mode = GPIO MODE OUTPUT; 
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gpioConfig.pull_up_en = GPIO PULLUP_ DISABLE; 
gpioConfig.pull down _en = GPIO PULLDOWN ENABLE; 
gpioConfig.intr type = GPIO_INTR_DISABLE; 
gpio_config (&gpioConfig) ; 




















See also: 


gpio_pad_select_gpio 
gpio_set_direction 
gpio_set_level 
gpio_config 


Pullup and pull down settings 

We commonly think of an input GPIO pin as having either a high or low signal supplied 
to it. This means that it is connected to +ve or ground. But what if it is connected to 
neither? In this case, the pin is considered to be in a floating state. There are times 
where we wish to define an unconnected pin as logically being high or low. An 
unconnected pin that is to be considered high is termed "pulled up" while an 
unconnected pin that is to be considered low is termed "pulled down". This comes from 
the physical hardware practice of attaching resistors to pull up or pull down the signal 
when it otherwise would be floating. 


In the ESP32 SDK, we can define a GPIO as being pulled-up or pulled-down by using 
the gpio_ set pull _mode() function. This function takes as input the pin number we 
wish to set and the pull mode associated with that pin. 


For example: 


gpio_set_ pull _mode(21, GPIO_ PULLUP_ONLY) ; 
See also: 


gpio_set_pull_mode 


GPIO Interrupt handling 

If we consider that the signal on a pin can move from high to low or from low to high, 
such a change might be something our application would be interested in Knowing. To 
determine when such a change happens, we can continually poll the value to detect a 
transition change. However this in not the best solution for a number of reasons. First, 
we have to busily perform checking to see whether a value has changed. Secondly, 
there will be a latency from the time the event happens to the time when we check. 
Thirdly, it is possible to completely miss a signal change if the duration of the change is 
short. For example, if we check the value of a pin and find it high and then immediately 
after it goes low and then high again, the next time we poll we will still see the pin high 
and never have known that it was ever low for a short period. 
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The solution to all these problems is the notion of an interrupt. An interrupt is similar to 
your doorbell at your house. Without a door bell (or listening for someone knocking) 
you would have to periodically check to see if there is anyone at the door. This wastes 
your time for the majority of instances where there is no-one there and also makes sure 
that when there is someone there, you attend to them in a timely fashion. 


In the land of ESP32s, we can define an interrupt callback function that will be called 
when a pin changes its signal value. We can also define what constitutes a reason for 
invoking the callback. We can configure the callback handler (technically called an 
interrupt handler) on a pin by pin basis. 


First, let us consider the interrupt callback function. This is registered with a call to 
gpio isr register() which takes a callback handler that is invoked when an interrupt 
occurs on any GPIO pin occurs. Within the callback handler, we can then ask for the 
interrupt flag status with: 

















uint32 t gpio_intr status = 
uint32 t gpio intr status h 





READ PERI _REG(GPIO_ STATUS_REG) ; // 0-31 
= READ PERI REG(GPIO STATUS1 REG); // 31-39 























Alternative, we can use the GPIO global variable which is a pre-mapped structure and 
access: 


* GPIO.status witc — Flags for GPIOO to GPIO31 
* GPIO.statusl wltc.val — Flags for GPIO32 to GPIO39 








We can enable or disable interrupt handling on a GPIO by GPIO basis by calling 


gpio intr enable(). 


To enable an interrupt for a specific pin, we use the function called 
gpio set intr type(). This allows us to set the reason that an interrupt might occur. 
The reasons include: 





* Disable — don't call an interrupt on a signal change. 


* PosEdge — Call the interrupt handler on a change from low to high. 
ISR called 


/ 
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* NegEdge — Call the interrupt handler on a change from high to low. 
ISR called 


/ 





* AnyEdge — Call the interrupt handler on either a change from low to high ora 
change from high to low. 
ISR called 


< 


¢ Hi -— Call the interrupt handler while the signal is high. 
* Lo — Call the interrupt handler while the signal is low. 


The interrupt handler can be flagged to be loaded into instruction RAM at compilation 
time. The default is that the generated code can live in flash. By flagging it up front as 
living in instruction RAM, it will always be there and ready to immediately be executed. 


For example: 
void IRAM ATTR my _gpio_isr handle(void *arg) { 
} 


A second implementation of interrupt handling is also provided that allows us to register 
a callback function associated with any given pin. This alleviates us from having to 
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write switch code in a common interrupt handler. Think of it as a high level set of 
convenience functions. 
Here is an example interrupt processor: 


static char tag[] = "test_intr"; 
static QueueHandle t ql; 


#define TEST _GPIO (25) 
static void handler(void *args) { 





gpio_num_t gpio; 
gpio = TEST GPIO; 
xQueueSendToBackFromISR(ql, &gpio, NULL); 








void testl_task(void *ignore) { 
ESP_LOGD(tag, ">> testl_task"); 
gpio_num_t gpio; 





ql = xQueueCreate(10, sizeof (gpio_num_t)); 





pio config _t gpioConfig; 
pioConfig.pin_bit_mask = GPIO SEL 25; 
pioConfig.mode = GPIO MODE INPUT; 
pioConfig.pull_up_en = GPIO PULLUP DISABLE; 
pioConfig.pull down _en = GPIO PULLDOWN_ ENABLE; 
pioConfig.intr type = GPIO_ INTR_POSEDGE; 
gpio_config(&gpioConfig) ; 





























g 
g. 
g. 
g. 
g. 
g 











gpio_install_isr service(0); 
gpio_isr handler add(TEST GPIO, handler, NULL); 
while(1l) { 

ESP _LOGD(tag, "Waiting on queue"); 














BaseType t re = xQueueReceive(ql, &gpio, portMAX DELAY) ; 











ESP_LOGD(tag, "Woke from queue wait: %d", rc); 





} 
vTaskDelete (NULL) ; 


} 
See also: 


Interrupt Service Routines — ISRs 
gpio_install_isr_service 
gpio_isr_handler_add 
gpio_isr_handler_remove 
gpio_isr_register 
gpio_intr_enable 
gpio_intr_disable 


Expanding the number of available GPIOs 


Although the ESP devices only have a limited number of GPIO pins, that needn't be a 
restriction for us. We have the capability to expand the number of GPIOs available to 


us through some relatively inexpensive integrated circuits. 
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PCF8574 
One of the available GPIO expanders is called the PCF8574. (The PFC8574A is the 
same but has a different set of addresses). 


This is an I?C device and hence works over only two wires. Using this IC we supply a 3 
bit address (000-111) that is used to select the slave address of the device. Since each 
address has 8 IOs and we can have up to 8 devices, this means a total of 64 additional 
pins. 

It appears that the device will use a pull-up resistor for a high and bring the pin to 
ground for low. This means that we can't use the pins for a high current source but can 
for low. 


Here is the pin diagram for the device: 


SCL 


INT 





Here is a description of the pins: 






































Symbol Pin Description 

A0-A2 1, 2,3 Addressing 

PO-P7 4,5, 6, 7,9, 10, 11, 12 Bi directional I/O 

INT 13 Interrupt output 

SCL 14 Serial Clock Line 

SDA 15 Serial Data Line 

Vopp 16 Supply Voltage (2.5V — 6V) 
Vss (Ground) 8 Ground 





The address that the slave device can be found upon is configurable via the ao-a2 pins. 
It appears at the following address: 


PCF8574 
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0 [1] | 0 ]a2|at] Ao | 





PCF8574A 





0; 141) 1 |A2;Al| AO 





























The pins ao-a2 must not float. 


This results in the following table: 





























A2 Al AO | Address | Address 
PCF8574 | PCF8574A 
0 0 0 0x20 0x38 
0 0 1 0x21 0x39 
0 1 0 0x22 Ox3a 
0 1 1 0x23 0x3b 
1 0 0 0x24 Ox3c 
1 0 1 0x25 Ox3d 
1 1 0 0x26 Ox3e 
1 1 1 0x27 Ox3f 























Here is an Arduino example program that drives LEDs to create a Cylon effect. 


#include <Wire.h> 
#include <Ticker.h> 
// SDA - Yellow - 4 
// CLK - White - 5 


#define SDA PIN 4 
#define CLK PIN 5 


Ticker ticker; 
int counter = 0; 
int dir = 1; 


void timerCB() { 
Wire.beginTransmission (0x20); 
Wire.write(~((uint8 t)1<<counter) ); 
Wire.endTransmission(); 








counter += dir; 
if (counter == 8) { 
counter = 6; 
dir = -1; 
} else if (counter == -1) { 
counter = 1; 
dir = 1; 
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void setup () 
{ 
Wire.begin(SDA_PIN,CLK PIN); 
ticker.attach(0.1, timerCB); 
} 


void loop () 


{ 
} 


The corresponding circuit is: 


0022 
8y 





And on a breadboard: 
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See also: 





8BIT IO EXPANDER (PCF8574) 
Datasheet — NXP 
YouTube — ESP32 Technical Tutorial: PCF8574 GPIO Extender 


Product page — TI 
Working with I2C 








MCP23017 

The MCP23017 from Microchip is a 16 bit input/output port expander that uses the I2C 
interface. The device can operate from 1.8V to 5.5V. The going price for an instance of 
one of these on eBay is about $1. The device has 16 GPIO pins that can be set as 
input or output controlled in two banks (ports). We can read or write the values of one 
bank at a time meaning that if we want to write all 16 bits, this would be two I2C 
operations and the same for reading. The device is also capable of generating 
interrupts for input signal detection. If we imagine a 100KHz clock rate, then to switch a 
bit on or off (and we can do these in groups of 8) then that would be 3 bytes of data plus 
acknowledgments ... ~30 bits ... which would imply a maximum switching rate of about 
0.3ms. The MCP23017 can operate at a variety of speeds including 100KHz and 
400KHz. 


The pin interface is: 
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Pin Label Description 

1 GPBO Bi-directional I/O 

2 GBP1 Bi-directional I/O 

3 GBP2 Bi-directional I/O 

4 GBP3 Bi-directional I/O 

5 GBP4 Bi-directional I/O 

6 GBP5 Bi-directional I/O 

7 GBP6 Bi-directional I/O 

8 GBP7 Bi-directional I/O 

9 VDD Power (3.3V —5V) 

10 VSS Ground 

11 NC Not connected 

12 SCL Serial clock input 

13 SDA Serial data input/output 
14 NC Not connected 

15 AO Address pin 

16 Al Address pin 

17 A2 Address pin 

18 RESET _ | Hardware reset 

19 INTB Interrupt output for port B 
20 INTA Interrupt output for port A 
21 GPAO Bi-directional I/O 

22 GPA1 Bi-directional I/O 

23 GPA2 Bi-directional I/O 

24 GPA3 Bi-directional I/O 

25 GPA4 Bi-directional I/O 

26 GPAS5 Bi-directional I/O 

2 GPA6 Bi-directional I/O 

28 GPA7 Bi-directional I/O 





The I2C address of the device is 7 bits given by 





GOlS|/e][sa)i2i] a] 0 
0; 10) 0 |A2;Al) AO 
































And hence has addresses in the range 0x20 — 0x27. 
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The register addresses are: 
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Register | Name Description 
address 
0x00 IODIRA Direction control for port A: 

¢ 1-%input 

* 0-output 
0x01 IODIRB Direction control for port B: 

¢  1-—%input 

* 0-output 
0x02 IPOLA Polarity inversion for input for port A: 

¢ | - inverted 

* 0-as-is 
0x03 IPOLB Polarity inversion for input for port B: 

¢ | - inverted 

* 0-as-is 
0x04 GPINTENA Interrupt enable for a change for port A: 

¢ 1-Enable input pin for interrupt on change event 

¢ 0 —Disable input pin for interrupt on change event 
0x05 GPINTENB Interrupt enable for a change for port B: 

¢ 1-Enable input pin for interrupt on change event 

¢ 0-—Disable input pin for interrupt on change event 
0x06 DEFVALA Default values for interrupt change comparison for port A. 
0x07 DEFVALB Default values for interrupt change comparison for port B. 
0x08 INTCONA Interrupt control for port A: 

* 1-—Compare the value on the pin to the value in DEFVALA 

* 0 -—Compare the value on the pin to its previous value 
0x09 INTCONB Interrupt control for port B: 

¢ 1 —Compare the value on the pin to the value in DEFVALB 

* 0 -—Compare the value on the pin to its previous value 
Ox0a IOCON Same register as 0x0b 
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Bit Label Description 





ei BANK Register mapping: 
¢ Registers in banks 
¢ Registers sequential 





6 MIRROR __| Interrupt pin mapping: 

¢ 1 -INT pins connected 

¢ 0 -INT pins separate. INTA is associated 
with port A and INTB is associated with port 
B 





5 SEQOP Sequential operation mode: 
¢ 1 —Sequential operation disabled 
* 0 — Sequential operation enabled 




































































4 DISSLW Slew rate control 
3 HAEN Hardware address enable 
2 ODR Open drain output for INT 
1 INTPOL Polarity of INT output: 
* 1 -<Active high 
* 0-Active low 
0 N/A Not used. Set as 0. 
0x0b IOCON Same register as 0x0a 
0Ox0c GPPUA Pull up control for Port A: 
¢ 1 —Pull-up via a 100K resistor 
¢  0-Pull-up disabled 
Ox0d GPPUB Pull up control for Port B: 
¢ 1-—Pull-up via a 100K resistor 
¢ O0-Pull-up disabled 
Ox0e INTFA Interrupt flags for Port A: 
¢ 1 —Pin caused an interrupt 
¢ 0 —No interrupt detected 
Ox0f INTFB Interrupt flags for Port B: 
¢ 1-—Pin caused an interrupt 
* 0Q-—No interrupt detected 
0x10 INTCAPA Values of GPIO when interrupt occurred on port A: 
¢  1—Pin was high 
¢ 0 -Pin was low 
0x11 INTCAPB Values of GPIO when interrupt occurred on port B: 
¢  1—Pin was high 
¢ 0-Pin was low 
0x12 GPIOA Read — Reads the values on port A 
0x13 GPIOB Read — Reads the values on port B 
0x14 OLATA 
Ox15 OLATB 
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See also: 


Data sheet 
Github: code fragment 
Github: telanoc/esp32_generic_i2c_rw 








Interrupt Service Routines - ISRs 
Imagine that you have written an ESP32 application in C. As you write that application, 
you make assumptions about what will happen. Imagine you write: 


statement A; 

statement B; 

statement C; 

Your assumption is that the program will perform statement A and then move on to 
statement B and then move on to statement C. In addition, if you have variables that 
are defined, unless the statements change those variables, you expect them to have the 
same values at the start as at the end. These are assumption that you should be able 
accept as true. 
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With an ESP32, we are programming a lot closer to the hardware than in some other 
environments. When working with hardware, events may happen externally to the 
ESP32 that require our attention. A GPIO might transition its signal level or new 
network packet arrive or serial data appear. In each of these cases (and more) it might 
be necessary to interrupt what ever we may be doing at the time and handle that event. 
To achieve this, we have access to what are called "Interrupt Service Routines" or ISRs. 
These are commonly C functions that we provide references to that may be invoked at 
almost anytime. They may be invoked between C statements or even during C 
statements. The state of the currently running program is saved and a "context switch" 
occurs causing the ISR to run. In order to maintain sanity, when you write an ISR there 
are rules that you absolutely must follow. 


First an ISR must be as short as possible. Remember, when you jump into an ISR the 
ISR has no knowledge of what you were doing when the interrupt occurred. You may 
have been doing something that was time critical and you have to get back to as quickly 
as you can. You most certainly must never perform any activity which might be 
blocking. 


Next, you must assume little about the state of the environment. You can't assume 
values of variables that you don't own and you absolutely must not change variable 
values that you don't own. Never mind being risky, trying to debug problems that show 
up once in ever 1000 runs because the timing was "just right" is a nightmare to be 
avoided. 


You should never invoke something that might result in another interrupt being 
generate. This can result in a never ending loop where an ISR causes an immediate 
interrupt which is processed when you return from the ISR which then goes on and on. 


With these limitations in mind, what then can you do? The answer is to design a 
solution that correctly anticipates and handles interrupt requests. There is no one 
formula that fits all but generally, if you can respond to the interrupt immediately with 
little or no side effects, then it is safe to do so. For example if an interrupt signals that a 
GPIO pin has changed value, you might update a memory location that is defined to 
reflect the "current" state of the pin and then immediately return. If you have to perform 
extended processing, then consider writing a message to a queue or unlocking a 
semaphore and then again, immediately returning. Since the ESP32 employs 
FreeRTOS which provides a preemptive task scheduler, you can have tasks that run in 
the background that "wake up" when events occur. These wake-ups need to be 
decoupled from the ISR and a queue or semaphore is a great way to achieve that. The 
following APIs are safe in ISR routines: 


* xTaskResumeFromISR() 
¢ xTaskNotifyGiveFromlSR() 
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xTaskNotifyAndQueryFromlSR() 
xTaskNotifyFromISR() 
xQueueSendFromlSR() 
xQueueSendToBackFromISR() 
xQueueSendToFrontFromlSR() 
xQueueReceiveFromlSR() 
uxQueueMessagesWaitingFromlSR() 
xQueueOverwriteFromlSR() 
xQueuePeekFromISR() 
xQueuelsQueueFullFromlSR() 
xQueuelsQueueEmptyFromI!SR() 
xQueueSelectFromSetFrom!SR() 
xSemaphore TakeFromISR() 
xSemaphoreGiveFromlSR() 
xTimerStartFromlSR() 
xTimerStopFromlSR() 
xTimerChangePeriodFromlSR() 
xTimerResetFromlSR() 
xTimerPendFunctionCallFromlSR() 
xEventGroupSetBitsFromlSR() 
xEventGroupClearBitsFromlSR() 
xEventGroupGetBitsFromlSR() 


Working with I2C 

The I2C interface is a serial interface technology for accessing devices. It has two 
signal lines called SDA (Serial Data) and SCL (Serial Clock). The ESP32 can act as a 
master and the devices connected downstream act as slaves. Up to 127 distinct slaves 
are theoretically attachable. Each slave device has a unique address and the master 
decides which slave is to receive data or be allowed to speak next. In addition, the 
ESP32 can also be a slave device communicating with an external master. 
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All the slaves connected use an "open drain" connection to the bus. This means that 
when they connect, their attachment is either open circuit or ground as an output. 
Because of this it is impossible for there to be an electrical conflict as it would be 
impossible for one device to assert a high signal while another tried to assert a low 
signal. The presence of a logical high signal occurs when the current slave device goes 
open circuit. This means that we need pull-up resistors on the lines such that when no- 
one is actively asserting a low signal, they are pulled-up to a logical high signal. A 
resistor value of 4.7KQ is recommended. 





The start of a transmission is indicated when the SCL is left high and SDA is pulled low. 
This informs all the slave devices that an address is about to be issued. When the 
address is seen by all the slaves, only one of them should match and the other devices 
ignore the request. 


The address of a slave follows the initial start indication and is comprised of 7 bits with 
most significant bit first. Following the 7 bit address is a final 8" bit that indicates 
whether this is a read or a write request. A value of 1 indicates a read from the slave 
while a value of 0 indicates a write from the master. 


On the SDA line, immediately after the 8 bits of address, comes the acknowledgment 
bit. This bit is not transmitted from the master to the slave but is instead transmitted 
from the slave to the master. Be sure you understand that as when looking at diagrams 
showing data on the SDA wire, those diagrams typically do not show the origination of 
the data, only their sequence. The turn around time from the last bit of the 8 bit 
address/direction data sent from the master to the acknowledgment bit sent from the 
slave happens without missing any clock cycles so has to be fast. A value of 0 in the 
acknowledgment states that the slave has received the data. A value of 1 in the 
acknowledgment states that no-one is responding or the slave is not present. 


Following this addressing frame comes the data frame or frames. For a master write 
request, the master will send 8 bits of data and expect a single bit of acknowledgment. 
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For a read from the slave, the slave will send 9 bits of data (8 data bits and an 
acknowledgment). 


The master will finally send an end of communication (or stop) indication which is a 
transition to high on the clock with NO corresponding transition to low and then a 
transition from low to high on the SDA line. 


See also: 


12C Bus 
Sparkfun — Tutorial: 12C 


Using the ESP-IDF I2C driver 

The ESP-IDF provides an |2C driver that allows us to control I2C functions from a C 
program at a high level without having to resort to low level register manipulation. 

Within the ESP32, the I2C functions are baked into the hardware of the IC and the 
drivers make working with I2C significantly simpler. The ESP32 can provide the 
services of both an I2C master controller as well as the ability to be an I2C slave. There 
are two independent I2C ports so we can participate in two I2C buses simultaneously ... 
either as two masters, two slaves or one master and one slave. Or, obviously, if we only 
need one bus, we can just ignore the other. The two ports are named 12c_num_0 and 
r2c NUM 1. Before we can use an I2C port, we need to configure it. 


In many ICs, the pin numbers exposed for I2C are fixed. This is not the case in the 
ESP32. Arbitrary exposed pins can be used for I2C. Since I2C is a "two wire" bus with 
one wire for clock and the other for data, for each I2C port we want to use we have to 
select two pins for these purposes. One pin will be the "sc1" (clock) pin and the other 
will be the "sda" (data) pin. 


To use I2C, we must configure the I2C environment. This involves a call to 
i2c_param_config(). This function takes two parameters. The first is the I2C port we 
are going to configure and the second is a structure containing the details of the 
configuration. Within this structure we have the following fields: 


* mode — The mode that we are configuring this I2C port. This is where we define 
the I2C participation of the ESP32 as either a master or a slave. The choices we 
can supply here are either 12c_ MODE MASTER Of I2C_MODE SLAVE. 


























* sda io num, scl_io num-— These two fields define the pin number we will use for 
data and clock. Again, there are no fixed/pre-defined pin numbers. 


* sda pullup en, scl _pullup en-— These two fields define whether the pins 
selected for data and clock will be pulled-up to a default of high. 
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* clk speed -— This field defines the clock speed of the bus when it is a master. A 
value of 100000 is normal for an I2C standard mode 100KHz bus but the ESP32 
also supports the I2C fast mode 400KHz bus. 


Here is an example: 


i2c_config t conf; 
conf.mode = I2C_ MODE MASTER; 
conf.sda_io_ num = 25; 














conf.scl_io_ num = 26; 

conf.sda_pullup_en = GPIO_PULLUP_ENABLE; 
conf.scl_ pullup_en = GPIO_PULLUP_ENABLE; 
conf.master.clk speed = 100000; 























i2c_param_config(I2C_NUM_0, &conf); 


After we have configured how we want our I2C bus to behave, we can enable it by 
actually installing the driver. We do this with a call to i2c_ driver instal1(). When 
calling this function we name the port, whether we are a master or a slave and, if we are 
a slave what buffer sizes to use. 





For example, when being a master: 





i2c_ driver _install(I2C_NUM_0, I2C_ MODE MASTER, 0, 0, 0); 














Once we have initialized the I2C environment, we can now start thinking of the 
permutations of actions that we wish to perform. If we are an I2C master, then we can 
perform a write operation to an identified slave or perform a read operation to an 
identified slave. 


First let us refresh ourselves on the notion of slave addresses. A slave address is 
typically 7 bits of address plus 1 bit flag of whether this is a read or write operation. 





Address (7 bits) Read or Write 
Add6 |Add5 |Add4 |Add3 |Add2 |Add1 |Add0  |R/W 



































A read operation is a'"1" and a write is a"O". These are defined as the constants 

I2C_ MASTER READ and I12c MASTER WRITE SO we don't have to remember these values. If 
we want to read from a device at address 0x12 ... then our transmitted I2C address 
would be (0x12 << 1) | I2C_ MASTER READ while if we wished to write to a device at 
address 0x12, our transmitted I2C address would be (0x12 << 1) | I2C MASTER READ. 









































To send a command, we build the structure of that command then ask for it to be 
transmitted. We start by creating a command handle using i2c_ cmd link create(). 
Next we declare that the command starts with an I2C start request by calling 

i2c_ master start (cmd). Now we can associate the data we wish to send with that 
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command by calling i2c master write byte() and/or i2c master write(). Next, we 
indicate that the command population has been completed. Now we can actually ask 
the ESP32 to perform the command with a call to i2c_ master _cmd_begin(). This API 
causes all the commands buffered to be transmitted. After calling 
i2c_master cmd begin(), we should release the command handle and create a new 
one for the next transmission. 


Here are some examples. Imagine we want to send the byte 0x34 to the slave at 
address 0x12: 


i2c_cmd_handle t cmd = i2c_cmd_link create(); 
i2c_ master start (cmd); 

i2c_ master write byte(cmd, (0x12 << 1) | I2C_ MASTER WRITE, 1 /* expect ack */); 
i2c master write byte(cmd, 0x34, 1); 











i2c_master stop (cmd) ; 
i2c_ master cmd_begin(I2C_NUM_0, cmd, 1000/portTICK_PERIOD MS); 
i2c_cmd_link delete (cmd) ; 











When working with I2C, | recommend that once you have attached the devices to your 
I2C bus then run an I2C scanner to ensure that they are responding properly. If we 
think about an I2C slave devices, when the master starts a transaction and transmits 
the address of the slave, the slave will respond with a positive acknowledgment ... 
assuming it is present to respond. If there is no such slave with that address, there 
obviously won't be such a response. As such, if we walk through each of the possible 
I2C addresses and start a transactions merely to see if we get a response, we can build 
a map of which slaves are present and which are not. An example ESP-IDF program 
that just does that can be found here: 





https://github.com/nkolban/esp32-snippets/blob/master/i2c/scanner/i2cscanner.c 


An example output might be: 


0 12 3 4 5 6 7 8 9 a bedeéi ff 








00: w= -- -- =H -- -- -- == == == == -- 
10: -- -- -- -- == 75-5 5 we we w= -- we == -- 
20: 20 -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
30: -- -- -- -- -- == -- == == we == = = == -- =e 
40: -- -- 35 25-5 He we we we wwe we == == -- -- 
50: -- -- -- -- -- == 25-5 we we wee = we He =e 
60: -- -- -- -- -- -- == -- =e -- -- = = =e =e =e 
70: -- -- -- 25 3-5 -- -- = 

See also: 


i2c_cmd_link_create 
i2c_cmd_link_delete 
i2c_master_start 
i2c_master_stop 
i2c_master_cmd_begin 
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i2c_master_write 
i2c_master_write_byte 
i2c_driver_install 
i2c_param_config 


Using Arduino I2C libraries 

The Arduino libraries provide an interface to I2C. At a high level we request a handle 
that we use to communicate as an I2C master to a connected I2C slave. We use the 
i2clnit() method to obtain such a handle. The handle is an instance of a pointer to an 
i2c_t piece of data. 


See also: 


i2clnit 
Arduino Wire Library 


Common I2C devices 
The following is a partial list of some of the more popular I2C based devices. 



























































Device Description Address 
ADS1015 Analog to Digital 

DS1307 Real Time Clock 0x68 
BH1750FVI Light level sensor 0x23 
HMC5883L Compass Ox1E 
MCP4725 Digital to Analog 

MCP23017 GPIO extender 0x20-0x27 
MPU6050 Accelerometer / Gyroscope 0x68 
MPU6500 Accelerometer / Gyroscope 

MPU9255 Accelerometer / Gyroscope / Compass 

PCA9685 PWM controller 

PCF8574 GPIO extender 0x20-0x27 
TEAS5767 FM Radio 

See also: 


Compass — HMC5883L (aka GY-271) (aka CJ-M49) 
Ambient light level sensor — BH1750F VI 

MCP23017 

Accelerometer and Gyroscope — MPU-6050 (aka GY-521) 
Real time clocks 
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Working with SPI - Serial Peripheral Interface 
SPI is a bus protocol that will allow an ESP32 to communicate with peripheral devices 
or ICs that comply with the SPI protocol. Logically, it looks as follows: 





Within the protocol, one device (typically the ESP32) acts as the bus "master" and all 
the other devices act as bus "slaves". What this means is that the communication is 
between the master and one individual slave at a time. The slave devices don't 
communicate with each other. The value of a bus is that we can attach multiple devices 
to the ESP32 (the master) using only a few wires as opposed to having to have multiple 
wires out to each individual device. 


Within the SPI protocol there are primarily three connections (wires) to each device. 


The first is called the "clock" line. This is an outbound signal from the master which is 
used to synchronize activities between all the participants. It is usually a regular 
high/low equally spaced train of signals. The frequency of the clock defines the speed 
of transmission across the bus. When the clock transitions from high to low or low to 
high, this is an indication in the SPI protocol that the slave device should either send or 
receive data. 


The next line we will look at is a data line that is exclusively written by the master and 
read by the slaves. The line is called the "Master Out / Slave In" which is an excellent 
description of its purpose. Commonly this is abbreviated to MOSI. The master serially 
streams data outbound down this line and the slave receives the data. The data bits on 
the line are synchronized with the clock line so that the slave knows when the next bit is 
ready to be read. 


The third line is also a data line that is exclusively written by a slave and read by the 
master. The line is intelligently called "Master In / Slave Out" and abbreviated to 
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"MISO". Again, the clock line is used to indicate when the slave should transitions its 
output bits. 


If there were only one device to which the master were communicating, these three 
lines would be sufficient ... however that isn't much of a bus. If we have multiple 
devices, the obvious problem is how does one slave know that it is being talked to as 
opposed to some potentially distinct slave? The answer is that each slave has a unique 
input line called the "Slave Select". Normally the slave select has one value (eg. high) 
and only when the master drives the slave select to the other value (eg. low) does that 
slave know that it is being addressed. The rules state that a slave should only respond 
(receive or transmit) on the bus when its slave select line indicates that it is to do so. 


Slave 
Selects 





CLK 
405 
MISO 


While a device is active because it is selected by the master, it can simultaneously read 
data from the MOSI line while concurrently writing data to the master through the MISO 
line. Focusing on a single master/slave interaction, the story looks like: 


MISO 





Since this is a serial protocol and we will receive data in bytes, we need to be cognizant 
of whether or not data will arrive LSB first or MSB first. There will be an option to 
control this. 


For the clock, we will be latching data and we will need to know what edges and 
settings are important. There will be a clock mode option to control this. In SPI there 
are two attributes called phase and polarity. Phase (CPHA) is whether we are latching 
data on high or low and Polarity (CPOL) is whether high or low means that the clock is 
idle. 
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CPOL=0 means clock is default low, cpoL=1 means clock is default high. 
When cro.=0, then the following are the values for CPHA 


CPHA=0 means data is captured on clock rising edge, cPHA=1 means data is captured on 
clock falling edge. 


When cro.=1, then the following are the values for CPHA 


CPHA=0 means data is captured on clock falling edge, cpHA=1 means data is captured on 
clock rising edge. 


SPI wraps these two flags into four defined and named modes: 

















Mode Clock Polarity - CPOL Clock Phase —- CPHA 
SPI_MODEO 0 (Clock default low) 0 
SPI_MODE1 0 (Clock default low) 1 
SPI _MODE2 1 (Clock default high) 0 
SPI _MODE3 1 (Clock default high) 1 




















The default for most purposes will be mopEo. 





Also for the clock, what speed are we will need to know what speed the data is to be 
moved. There will be a clock control speed option to control this. 


Using the ESP-IDF SPI driver 

Unlike other devices and processors on the market, the ESP32 doesn't dictate that a 
fixed set of pins must be used for the CLK, MOSI and MISO functions. Instead the pins 
that you select will perform these functions. Should you be designing PCBs this opens 
up many more levels of flexibility as it simplifies connectivity and link routing. 


Because the ESP32 doesn't limit you to just one SPI bus, the utilization of SPI on 
ESP3z2 is architected into a set of discrete steps. 


1. We initialize a bus defining its nature. 


2. We describe a device to the ESP32 that is attached to a configured bus. From 
this we get a handle that refers to that device. 


3. We communicate with a device using its handle reference. 


We use the notion of a transaction to describe the ESP32 interacting as a master with a 
slave peripheral. 
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We can imagine there being the following actions performed: 
¢ Acommand is sent 
¢ An address is sent 
¢ Data is read from the slave and simultaneously data is written to the slave 


The command and address actions are optional and can be omitted resulting in only the 
parallel send and receive of data. 


The following illustrates the relationships between some of the logical components we 
will be working with from an SPI driver perspective. The Bus definition identifies the 
pins used for a bus for MOSI, MISO and CLK. Next we define a logical device and the 
characteristics of that device on the bus. Notice that the clock speed of the bus is an 
attribute of the device definition. When | first tried to understand this it confused me. 
Surely a bus has a clock speed that is the same for all devices? In the ESP32 we have 
more flexibility that ever before. The ESP32 can communicate with distinct devices 
using different bus speeds as a function of the currently selected device. For example, 
if we are talking with device "A", we may use a clock speed of 100KHz however if we 
are talking with device "B", we can use a different clock speed. Since only one device 
at a time has is active because of its slave selection, the other devices can ignore the 
clock rate (and other data lines) and hence speed of clock is not a consideration for a 
device that is not selected. 


Bus Definition 







MOSI Pin 
MISO Pin 
CLK Pin 





Device Definition 










SPI Mode 
Clock Speed 

CS Pin 
Callbacks 

Bit Order 






Send Data 
Receive Data 


Transmission 


To use the SPI driver, we start by calling spi bus initialize (). Here we identify the 
pins on the ESP32 that are to be used for SPI functions such as CLK, MISO and MOSI. 
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Next we call spi_bus_add_device() to tell the ESP32 about an external SPI device. 
This includes optionally nominating a pin for the slave selection (CS) as well as a clock 
speed for communications with that device. Calling spi bus add device() populates a 
handle for us that we can subsequently use to refer to that device. 


Once done, the ESP32 and external SPI device have a relationship and it is now 
possible for them to interact. We can either queue transactions using the call to 

spi device queue trans() and subsequently querying their results with a call to 

spi device get trans result () Of we can synchronously interact with the SPI device 
using a Call to spi_ device transmit (). 


Putting this all together, here is a sample that transmits a few bytes over a bus: 


#include <driver/spi_master.h> 
void test _spi_task(void *ignore) { 
ESP_LOGD(tag, ">> test _spi_task"); 





spi bus config t bus config; 





bus config.sclk_io num = clkPin; // CLK 
bus config.mosi_io num = mosiPin; // MOSI 
bus config.miso io num = misoPin; // MISO 
bus_config.quadwp_io num = -1; // Not used 
bus_config.quadhd_io num = -1; // Not used 
ESP_LOGI (tag, "... Initializing bus."); 

















ESP ERROR CHECK (spi bus _initialize(HSPI HOST, &bus_config, 1)); 


spi device handle t handle; 





spi_ device interface config t dev_config; 








dev_config.address bits = 
dev_config.command_bits = 
dev_config.dummy bits = 
dev_config.mode - 
dev_config.duty cycle pos = 
dev_config.cs_ena_posttrans = 


4" @. Or SO. -O.:O: 


dev_config.cs_ena_pretrans = 0; 


¢ 














dev_config.clock_speed_hz = 10000; 
dev_config.spics io num = csPin; 
dev_config.flags = 0; 
dev_config.queue_ size =. Aly 
dev_config.pre cb = NULL; 
dev_config.post_cb = NULL; 
ESP_LOGI (tag, "... Adding device bus."); 








ESP ERROR CHECK (spi _bus_add_device(HSPI HOST, &dev_config, &handle)); 











char data[3]; 

spi_ transaction _t trans desc; 
trans desc.address = 0; 
trans desc.command = 0; 
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trans desc.flags = 0 
trans desc.length =a 3 * 87 
trans desc.rxlength = 0 


trans desc.tx buffer = data; 
trans desc.rx buffer = data; 
data[0] = 0x12; 
data[1] = 0x34; 
data[2] = 0x56; 


ESP_LOGI (tag, "... Transmitting."); 
ESP_ERROR CHECK(spi_ device transmit (handle, &trans_ desc)); 





ESP LOGI (tag, "... Removing device."); 
ESP_ERROR_CHECK(spi_bus_ remove device (handle) ); 








ESP LOGI (tag, "... Freeing bus."); 
ESP ERROR CHECK (spi_bus_ free(HSPI_HOST)); 


























ESP_LOGD(tag, "<< test _spi_task"); 
vTaskDelete (NULL) ; 











If we then examine the result in the output of a logic analyzer we find: 

















See also: 


spi_bus_initialize 
spi_bus_add_device 
spi_device_transmit 
spi_device_queue_trans 
spi_device_get_trans_result 


The Arduino Hardware Abstraction Layer SPI 
The Arduino hardware abstraction layer for SPI provides a high level API for working 
with SPI. On an ESP32 there are multiple SPI peripherals so we need to always 
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identify which one we are working with. The identity of an SPI instance is contained 
within an "spi_t" instance. We get a pointer to one of these by calling "spistartBus". 


The pins on an ESP32 that can be used for SPI can be dynamically mapped. 
Remember that a single SPI instance can have up to 4 pins ... these are scx, MOSI, MISO 
and ss. For the three SPI interfaces supplied by ESP32, the following are suggestions 
with native support: 
































spr | most | MISO | CLK | SS 
HSPI| 13 12 14 15 
VSPI | 23 19 18 5 
[FsPi| 8 7 6 Ul 





Of these three, the rspz bus should not be used for applications as it is used internally 
by ESP32. 


The following diagram illustrates the default pin numbers for SPI for vspr and HsP7 ... 
but please realize that these are only defaults and can be re-mapped as needed. 


U 
= 
ww 
= 
Vv 
‘a 
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Once we have the SPI instance, we call spiAttachMOSI(), spiAttachMISO(), 
spiAttachCLK() and spiAttachss() to set the corresponding pin mappings. Passing a 
pin value of -1 uses the default otherwise the explicit pin number supplied is used. 


Once we have an SPI instance and attached the pins, we can start sending and 
receiving data. 





spi_t *spi = spiStartBus(VSPI, 1000000, SPI _MODEO, SPI MSBFIRST) ; 
spiAttachSCK (spi, sckPin); 

spiAttachMISO(spi, misoPin) ; 

spiAttachMOSI (spi, mosiPin); 

spiAttachSS(spi, 0, ssPin);//if you want hardware SS 
spiEnableSSPins(spi, 1 << 0);//activate SS for CSO 

spiSSEnable (spi); 








//transfer some data 

const char * data = "hello spi"; 

uint8 t out[strlen(data) ]; 

spiTransferBytes(spi, (uint8 t *)data, out, strlen(data)); 
//out now contains the response from the slave 


See also: 


spiStartBus 
spiAttachMISO 
spiAttachMOSl 
spiAttachSCK 
spiAttachSS 


Common SPI devices 

Now that we know about the existence of SPI, we might ask ourselves what kinds of 
peripheral devices are available for use? Here is a short list of some of the more 
interesting ones | have come across: 
































Device Description 

MAX7219/MAX7221 7 segment or 8x8 matrix LED controller. 
MCP3208 12 bit Analog to Digital 

Nokia 5110 / PCD8544 84x48 pixel LCD 

SSD1306 128x64 OLED display 

ST7735 128x128 display 

TJCTM24024-SPI 320x240 TFT display 

MFRCS522 RFID 

nRF24L01 Communications device 
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Working with UART/serial 

The goal of a data bus is to move information from one place to another. In our digital 
electronics world, the unit of information is a bit ... a value of 1 or 0. Typically we group 
these bits into a larger unit called a byte which a sequence 8 bits. These 8 bits can 
represent a numeric value from 0 to 255. 


Now let us suppose we have a CPU (eg. an ESP32) and a remote device which wants a 
piece of data that the ESP32 has. For example, we'll keep it simple, assume it is some 
kind of smart light bulb where a value of 0 means dark and a value of 255 means full 
luminance. How do we transmit our data from the ESP32 to the device? One way 
would be to have 8 parallel wires between the ESP32 and the device and we would 
simultaneously set each of the digital values on the wires to the 8 bits of our value. That 
works great ... but it has two draw backs. The first is that it means that we have to use 
thick cables carrying 8 separate discrete strands. It also limits us to only 8 bits of data. 
What if we want to send 24 bits of data such as the luminescence for red, green and 
blue? 


The data bus we are considering here is known as a parallel bus because we are 
sending data in parallel. However in our story, we are going to talk about a serial bus. 
Parallel Serial 


os 
—<—__—_ 10010110 
TX _—— 9 RX TX —_—_————_—— RX 
lL 
_——E 


Imagine if you will that that you can sense a remote value of either "1" or "0". Imagine 
you are miles away from your friend and you have a pair of binoculars. You can look 
through them and see that he has a flag pole whether the flag can either be all the way 
up or all the way down (he is so far away that you can't properly distinguish a flag in the 
middle of the pole and you aren't sure if it is all the way up or all the way down ... so you 
can only see the presence of absence of the flag). Can you use that to communicate? 


The answer is yes ... but it takes a little work. 


Let's imagine you and your friend agree on a timing rate ... lets say "10 seconds". What 
that means is that you will look through your binoculars every 10 seconds and write 
down whether the flag is high or low. You will ignore any other measurements. Your 
friend will also know that rate and won't change the flag any quicker or any slower than 
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once every 10 seconds (we'll assume he can magically change the flag from low to high 
or high to low instantly). 


You both start and you read the following flag values: 


* Q-up 

* 10-—up 

* 20-down 
¢ 30-up 

¢ 40 -down 
« 50-—up 

* 60-—up 

¢ 70-down 


This would correspond to the value 01101011. Ta da!! You have now transmitted 8 bits 
of data from one place to another ... simply by agreeing the rate of change. This rate 
of change is called the "baud rate" and is how many bits per second can be transmitted. 
In our story we transmitted 1 bit every 10 seconds ... and hence had a baud rate of 0.1. 
In the electronics world where we can sense at extremely high speeds, typical baud 
rates are 9600, 4800, 19200, 38400, 57600 and115200. As we see, we can send data 
very quickly. The primary requirement is that the baud rate used between a sender and 
a receiver be agreed upon. Our story won't work if they think that they are transmitting 
at different rates. 


The next part of our story is knowing when we are done. We could keep looking 
through our binoculars and writing down the flag position every 10 seconds ... but how 
much data is our friend sending? This is where the bit count comes into the story. 
Again, we agree how many bits constitute a unit of transmission. Typically this is 8 bits 
corresponding to a byte but the protocol allows us to agree on a transmission of 5, 6, 7, 
8 or 9 bits per transmission. 


If you are following the story, there is another puzzle we have to consider ... and that is 
when do we start recording data? If 1am going to sample the data once every period, 
when does that period start? The answer to that one is that every transmission of a unit 
of data starts with the signal high and when it goes low, that indicates that we have 
agreed that will be the start of the transmission period. Since we have the start 
indicated from a transition from high to low, then at the end of the last transmission, the 
signal must be left high ... and that's where a stop bit comes into play. An additional but 
of data is added at the end which drives the line high. 
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There are three hardware supported serial interfaces on the ESP32 known as UARTO, 
UART1 and UART2. Like all peripherals, the pins for the UARTs can be logically 
mapped to any of the available pins on the ESP32. However, the UARTs can also have 
direct access which marginally improves performance. The pin mapping table for this 
hardware assistance is as follows 


























UART RX IO TX IO CTS RTS 
UARTO GPIO3 GPIO1 N/A N/A 
UARTI1 GPIO9 GPIO10 GPIO6 GPIO11 
UART2 GPIO16 |GPIOI7 GPIO8 GPIO7 











Having said that, the UART drivers that | recommend to use don't have this level of 
optimization built into them and as a result, you are pretty much free to use any pins you 
choose. 


There is low level hardware serial support and higher level driver support. | recommend 
the driver level be used wherever possible. 


The driver APIs are included through the inclusion of "driver/uart.h". 


We start by populating a uart_config_t structure instance. This provides the core 
settings fora UART we want to use. An example might be: 


uart_config_ t myUartConfig; 























myUartConfig.baud_rate = UART_ BITRATE 115200; 
myUartConfig.data_bits = UART_DATA 8 BITS; 
myUartConfig.parity = UART PARITY DISABLE; 
myUartConfig.stop bits = UART_STOP BITS 1; 
myUartConfig.flow_ctrl = UART_HW_FLOWCTRL_ DISABLE; 
myUartConfig.rx flow _ctrl_ thresh = 120; 


Once populated, we can set the parameter of the UART with a call to 


uart_param_config(). 


Next we define the pins we wish to associate with our UART using uart_ set pin(). For 
example: 


21 22, 








uart_set_pin(uartNum, UART PIN NO CHANGE, UART_PIN NO CHANGE) ; 


x 


We can now initialize a driver using: 


uart_driver install (uartNum, 2048, 0, 10, NULL, 0); 
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One of the options we can specify when initializing a driver is to supply a FreeRTOS 
queue handle. If we supply this, then events that are detected by the UART are then 
posted onto the queue. We can have tasks that are blocked watching the queue ready 
to process incoming events when they arrive. This allows us to perform UART data 
processing asynchronously. If we don't want to use a queue, we specify NULL for the 
queue parameter. 


To write data to the UART we use the uart write bytes () function. 


See also: 


UART driver API 
UART low level APIs 
uart_param_config 
uart_driver_install 
uart_write_bytes 
Wikipedia — UART 
Serial Communication 





Using the VFS component with serial 

The ESP32 virtual file system (VFS) component provides an interface to UART. To use 
this, we initialize with a call to esp vfs dev uart register(). Following this we can 
perform file I/O operations against the VFS file system at the following paths: 


* /dev/uart/0 —-UARTO 
* /dev/uart/1 —UART1 
© /dev/uart/2 —-UART2 








Currently we can open, close, read and write to the device. 


See also: 


esp_vfs_dev_uart_register 


12S Bus 
The Inter-IC Sound (I2S) bus is a serial link protocol specifically for sound data. The 
protocol utilizes three lines. These are: 


¢ SCK — Serial Clock line. 


¢ WS —Word Select line. Indicates the channel being transmitted. 0 — channel 1 
(left), 1 — channel 2 (right). 


¢ SD - Serial Data line. 


See also: 


12S APIs 
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I2S bus specification 
Wikipedia: 12S 





RMT - The Remote Peripheral 

The primary purpose of this component of the ESP32 is to generate pulses sent via an 
infrared LED. When you point your TV remote control at your TV and press a button, an 
infrared LED at the front of your controller sends a sequence of pulses that are received 
by the TV and decoded. Since an infrared LED can be either "on" or "off" at any given 
time, the signal is encoded in the duration that the LED is either on or off. 


A data item in the RMT represents one bit of information and is composed of a 16 bit 
value. 








level [15] period [14:0] 








The level bit is either 1 or O describing the output signal while the period (15 bits in 
length) is the duration in clock ticks for which that level will be sent. 15 bits give us a 
range from 1-32767. A value of 0 for the period is used as an end marker. The normal 
maximum number of bit records is 128 (or 256 bytes of record data). 


The RMT has 8 distinct channels with each channel having 128 16 bit records. Should 
we wish to send more than 128 records, we can extend a channel to use the channel 
data of subsequent adjacent channels. For example, if we are using only channel 0 
then the data available for it can be that of channel 0, channel 1 up to channel 7 giving 
us a total of 1024 value records (1024 data items which means 1024 bits of data or 
2048 bytes of data items). 


There is also an interesting mechanism that involves the buffer for a channel wrapping 
around. Imagine that we have a default buffer size of 128 * 16bit records. If we need to 
send more than 128 records, we can pre-load a buffer with our first 128 values and set 
the RMT transmitting. When it has transmitted the first 128 values, it will generate an 
interrupt that can be used to re-fill the buffer with the new values and progress will 
continue. 


The hardware allocates 512 instances of 32 Bit records (512 * 32/8 = 2048 bytes) 

which can be read and written by the RMT hardware in the CPU. Each 32 Bit record 
contains two data items. Each channel has one block of 64 instances of 32 bit records 
associated with it which gives us 128 data items of wave form (1 transition is encoded in 
16 bits). 
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512 
entries 


512 
entries 


32 bits 


eee 


level period | level | period 
level eriod level | period 


level period level | period 


32 bits 


ee 


64 entries of 2 data items Channel 0 


64 entries of 2 data items Channel 1 
64 entries of 2 data items Channel 2 


64 entries of 2 data items Channel 7 


Should we need a transmission that is greater than 128 data items, we can consume 
the adjacent block which will give us a further 128 data items transitions. We can only 
do this by using channel block for the next higher adjacent channel. We can actually 
specify that we want to use ALL the channels for a single transmission giving us a 
maximum transmit bit transition of 8 x 128 = 1024. Note that there is no wrap around. 
So channel 0 can use the blocks of channel 0 through channel 7, channel 1 can use the 
blocks of channel 1 through channel 7 ... and channel 7 can only use its own memory 


block. 


To use the driver, one typically follows this recipe: 


Complete an rmt_config_t structure. 


Call rmt_config() passing in the rmt_config_t structure. 





Call rmt_driver install () to install the driver. 
Build an array of records to send. 


Call rmt_write_ items () to send the stream. 


Since RMT is all about setting signals for interval durations, there is a lot to be 
discussed about time. First we must discuss the base clock. By default this runs at 
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80MHz. That means it ticks 80,000,000 times a second or 80,000 times a millisecond 
or 80 times a microsecond or 0.08 times a nano second. Flipping this around, our 
granularity of interval is 1/80,000,000 is 0.0000000125 seconds or 0.0000125 
milliseconds or 0.0125 microseconds or 12.5 nanoseconds. | hope we agree, that's 
pretty fast. 


Since these are pretty small durations, we can "logically" slow our clock down for timing 
purposes. The base clock speed is 80MHz but we can provide a divider which is an 
integer value against which the base clock speed is divided to provide a new tick rate 
that is used as the interval value for timings. The integer value is 8 bits so we can 
divide between 1 and 255. At 255 we have are down to about 314KHz. Since the base 
speed is 80, it seems to make sense to divide by 8, 80 or 160, giving rates of 10MHz, 
1MHz and 500KHz. 


The period range of a cycle is 15 bits giving us a value between 1 and 2415 (32768). 
For example, if we divide the base clock by 80 then the granularity unit becomes 1 
microsecond so if we delay for 1000 units, we end up at 1msec. 


When there is no current transmission, we can set the idle level to be enabled and 
either high or low. This sets the output pin to this idle value when not in use. 


Here is a sample RMT application: 


#include <freertos/FreeRTOS.h> 
#include <freertos/task.h> 
#include <esp_log.h> 

#include <driver/rmt.h> 
#include "sdkconfig.h" 


static char tag[] = "rmt_tests"; 

static void dumpStatus(rmt_channel _t channel) { 
bool loop_en; 
uint8 t div_cnt; 
uint8 t memNum; 
bool lowPowerMode; 
rmt_mem owner t owner; 
uintl6 t idleThreshold; 
uint32_ t status; 
rmt_source clk _ t srcClk; 





rmt_get_tx_loop_mode(channel, &loop en); 


rmt_get_clk_div(channel, &div_cnt); 


rmt get mem block num(channel, &memNum) ; 





rmt_get_mem_pd(channel, &lowPowerMode) ; 


rmt_get_memory owner(channel, é&owner); 
get_rx_ idle thresh(channel, &idleThreshold) ; 


get_status(channel, &status); 


rm 


rm 








Gh Gks ete ste eit cr acct 


rmt_get_source_clk(channel, &srcClk); 
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ESP_LOGD(tag, "St 
ESP LOGD(tag, "- 
ESP LOGD(tag, "- 
ESP LOGD(tag, "- 
ESP LOGD(tag, "- 
ESP LOGD(tag, "- 
ESP LOGD(tag, "- 
ESP LOGD(tag, "- 
ESP LOGD(tag, "- 

} 

void runRmtTest() { 





ESP _LOGD(tag, ">> 


atus for RMT channel %d", channel); 


Loop enabled: %d", loop en); 
Clock divisor: sd", div_cnt); 
Number of memory blocks: %d", 





Memory owner: %s", Owner==RMT M 


memNum) 


Low power mode: %d", lowPowerMode) ; 





, 





Idle threshold: %d", idleThreshold) ; 


Status: Sd", status); 


Source clock: %s", srcClk==RMT_BASECL 


runRmtTest"); 


rmt_config_ t config; 


con 
con 
con 
con 
con 
con 
con 
con 
con 
con 
con 


fig 


fig. 
fig. 


fig 


fig. 
ELgs 
Fig: 
Ko pee 
fig. 
fig. 
fig. 





con 


ESP_ 


fig 








ESP 








ERROR_CHI 
ERROR_CHI 


-rmt_mode = 
channel = 

gpio_num = 
-mem_block __ 
tx config. 
tx_config. 
tx config. 
tx_config. 
tx_config. 
tx_config. 





tx_config. 
-clk_ div = 


CK (r 





Rt 
ry 
Rt 
ry 


RMT MODE TX; 

RMT CHANNEL 0; 
Ze 

num = 1; 








loop_en = 0; 

carrier en = 0; 

idle output_en = 1; 

idle level = 0; 
carrier duty percent = 50; 
carrier freq hz = 10000; 
carrier level = 1; 

80; 


mt_config(&config) ); 


dumpStatus (config.channel) ; 


rmt_item32_ t item 


items 
items 
items 
items 


items 
items 
items 
items 


items 
items 
items 
items 





0].duration 
-level0d = 
.-duration 
-levell = 





CoO °o 


.-duration 
-leveld = 
.duration 
-levell = 


PPP PR 


.-duration 
-level0 = 
.duration 
-levell = 


NM NM NY NY 





while(1) { 











ESP 


ERROR_CHI 





3, /* Numbe 
1 /* wait t 


s[3]; 
0 = 10000; 
1; 
1 = 10000; 
0; 


0 = 10000; 

1; 
1 = 5000; 
0; 














0 = 0; 
1; 

c= 
0; 


| 
jo) 
~ 


ECK(rmt_write items (config.channel, 


cr of items */ 
ill done */)); 





vTaskDelay (1000/portTICK_ PERIOD MS); 
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CK(rmt_driver install(config.channel, 0, 


items, 


EM OWNER TX?"TX":"RX") ; 





K APB?"APB (80MHz)":"1MHz") ; 


ESP_LOGD(tag, "<< runRmtTest") ; 





} 


So far we have discussed emitting a waveform of signals but there is a powerful second 
capability of the RMT and this to be able to capture received waveforms that might be 
arriving. 


To use the RMT in receiver mode, we call rmt_config() specifying that the rmt_mode of 
the given channel should be rut _mopE Rx. Note that a channel can be only one of a 
receiver or transmitter at any given time. Once a channel is configured to be a receiver, 
it will start watching the input and be considered to be in its idle state. When it starts to 
see transitions, it will begin recording their values and durations into RAM. It will 
continue to do this until it no longer sees transitions for a period of time known as the 
idle threshold at which time it will return to its idle state and write a termination record 
into the output data. A termination record is simply a data item that has a duration of 0. 
As an indicator that a signal train has been received, when it returns to idle state, an 
RX_END Interrupt is generated. There is also the ability to perform simple noise filtering. 
Records of a duration less than a configurable threshold can be automatically removed. 








To obtain the received data, we need to become familiar with the ring buffer functions. 
These are supplied as part of the RTOS set of functions. Through the RMT APIs, we 
can call rmt_get_ringbuf_handler() which returns an instance of RingbufHandle t 
which is a reference to a ring buffer who's buffer size is defined when we made the call 
to rmt_driver install(). Through this RingbufHandle t We Can then call 
xRingbufferReceive() to get (with optional blocking) an array of rmt_item32_t records 
that contains the received data. Once we are done with this, we call 
vRingbufferReturnItem() to release the storage. 


When working with RMT, measurement of times is crucial, after all that's the core of the 
story. When we consider the data structure representing a value is 16 bits long with 1 
bit used for the signal value, that leaves us 15 bits per measurement to encode the 
value. The maximum value a 15 bit integer can have is 65535 (2%16 — 1). Let us put 
this in perspective when looking at the following signal trace: 


do 


—_—_—_—_—_—_—_——oO"> 


dl 
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If we focus on just the start, we see that the signal was low for a duration of do and then 
high for a duration of a1. We measure duration in seconds and, of course we can 
perform simple arithmetic to scale into milliseconds or microseconds with just 
multiplication factors. 


Now let us think of the duration returned by RMT as a 15 bit value. That duration is not 
a direct measurement of time. It is actually a count of clock ticks. If you think of a wall 
clock with a second hand, each tick represents one second ... and hence one tick 
indicates one second has passed. The clock rate of our ESP32 is 80MHz (80 million 
ticks per second). That means that 1 tick is 1/80,000,000 of a second or 12.5 nano 
seconds. Note that is nano seconds and not milli or micro seconds. So if 1 tick is 12.5 
nano seconds, at 80MHz, the maximum duration that we can measure would be 15 bits 
worth of data or 65535 * 12.5 ns = 819us. And in there is the problem. 819us is still 
less than a millisecond and that is not much time at all. Many of the measurements we 
care about might be far more than this ... measurements in the 10s of milliseconds are 
not uncommon. If the maximum measurement we can take is 819us what is our 
solution? 


One way would be to increase the number of bits available in the recorded data but 
there is a better solution. We can "logically" use a slower clock. Imagine if the clock 
didn't tick at 80MHz but instead ticked at 800KHZz ... a factor of 100 slower. This would 
mean that 1 tick would be 1/800,000 of a second or 1.25 micro seconds. A 
measurement of 65535 tick would now have a duration of 81.9 milliseconds ... and that 
is more usable. The downside of this is that we have reduced the granularity of a tick. 
If we are measuring changes in signal which change faster than once every 1.25 
microseconds, then we will miss some of the changes. However, for the vast majority of 
purposes, we won't need that level of granularity. When we configure the RMT 
peripheral, we can supply a "clock divider" which is an 8 bit value that allows us to 
specify the divisor for our clock. 


Imagine our clock divisor is cLk_prv. The number of ticks in 10 micro seconds then 
becomes: 

TICK_10 US = 80,000,000 / CLK DIV / 100,000 

If we then are told by RMT that COUNT ticks have occurred, that would be: 


COUNT * 10 / TICK_10_US microseconds 


See also: 


Remote Control Peripheral — RMT 
rmt_config 

rmt_driver_install 

rmt_write_items 
rmt_wait_tx_done 
xRingbufferReceive 
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Ring buffer withing RTOS 
Chapter 7 of ESP32 Technical Reference Manual — Remote Control Periphera 


Timers and time 

The ESP32 leverages the FreeRTOS environment which provides the concept of a 
clock tick. This isn't a real-clock (as in a CPU clock) but is instead a logical timer period 
defined by the FreeRTOS. Currently, the default tick is one millisecond but this can be 
changed in the make menuconfig options (but | wouldn't recommend it). There is a 
constant called port TICK PERIOD ms that defines the duration (in milliseconds) of a 
FreeRTOS clock tick. 





Within our code, we may wish to delay for a period of time. We can use the 
vTaskDelay() function. This function takes as input the number of FreeRTOS ticks to 
sleep. We can convert from time to ticks using: 


timeValInMillisecs/portTICK PERIOD MS 





for example: 


vTaskDelay (timeValInMillisecs/portTICK_ PERIOD MS) 





Another aspect of working with time is time calculations and measurement. The 
function system get_time() returns a 32 bit unsigned integer (unit32_t) value which is 
the microseconds since the device booted. This value will roll over after 71 minutes. 


Note: system get _time() is deprecated, use gettimeofday() instead. 
When we use gettimeoday() we get back a struct timeval which contains two fields: 


* tv_sec— The time in seconds 





* tv_usec — The time in micro seconds 


The reason that a structure is returned is that it might not be possible to accommodate 
this value in a single number, especially on a 32bit system such as the ESP32. We may 
need to perform arithmetic on these values ... for example to measure the duration of 
some activity, we might get the time before and the time after and subtract one from 
another. A library of simple routines is provided here: 


https://github.com/nkolban/esp32-snippets/tree/master/c-utils 
called "c timeutils.c" and "c timeutils.h". The functions supplied include: 
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* struct timeval timeval_add(struct timeval *a, struct timeval *b) — Add 


two struct timeval structures together resulting in the sum. 


* void timeval addMsecs(struct timeval *a, uint32 t msecs) —Adda specified 
number of milliseconds to the timeval. 





* uint32_t timeval_durationBeforeNow(struct timeval *a) — Return the number 
of milliseconds since the past time. 








* uint32 t timeval_durationFromNow(struct timeval *a) — Return the number 
of milliseconds until the future time. 





° struct timeval timeval sub(struct timeval *a, struct timeval *b) — 
Subtract one time vale from another. 











* uint32_ t timeval_toMsecs(struct timeval *a) —return the number of 
milliseconds represented by the timeval. 


Another useful function is one supplied by FreeRTOS called xTaskGetTickCount(). This 
returns the number of clock ticks that have elapsed since FreeRTOS was started. We 
can use this to measure elapsed time between distinct points. 


What if we need a granularity of time smaller than a microsecond? Hopefully you won't 
need this often ... however some solutions such as working with the WS2812 LEDs do 
in fact require ultra fine precision. 


One possible solution is to drop down to assembly language programming. There is a 
special register managed by the ESP32 which is called "ccount" which measures cycles 
of operation. The value of this is incremented each time an operational cycle 
completes. 


The value of this register can be retrieved with the following C code: 


static inline uint32_ t getCycleCount() { 
uint32 t ccount; 
asm __volatile  ("rsr %0,ccount":"=a" (ccount) ); 


return ccount; 


} 


This fragment uses the in-line assembler to transform an assembly language statement 
into its corresponding operational instruction. 


A specialized function called xthal_ get ccount() provides a similar function. 


Note: The following is disabled in EPS32 at this time. 


Another mechanism to suspend execution is a call to nanosleep(). This takes as input 
a struct timespec that includes seconds and nanoseconds. Remember 1 second = 
1000 milliseconds = 1000000 microseconds = 1000000000 nanoseconds. 
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If we need additional timer functions, the ESP32 provides four high resolution timers 
that are divided into two groups of two. 


For the most part, when we want our applications to perform tasks at certain times or 
block for configurable amounts of time, the use of the FreeRTOS timers will be the best 
solution. 


After having looked at internal timing, let us now look at real-world or "wall clock" timing. 
The ESP-IDF provides a rich assortment of POSIX based APIs for working with wall 
clock times. There are two primary representations of a wall clock time those are 
"time t" which is basically a large integer. The value is the number of seconds that 
have elapsed since the point of time known as the "epoch" which is midnight on the 1* 
of January 1970 in GMT (near London England). Given a time_t value, we can 
calculate the date and time. Thankfully, we don't have to worry about that complex 
arithmetic as library functions are supplied for us. 


The second data type we will consider is a structure called "struct tm". This structure 
contains fields for all the useful date and time values such as the hour, minute and 
second as well as year, month and day (and a few more). When we start to think about 
wall clock time, a new consideration comes into play. If | look at my clock and it says 
3:51pm | know what time it is. However, that is my "local" time sitting in Texas. If | 
called a friend in London, he would say its 9:51pm. The reason for this is that the world 
is divided into distinct time zones and the declaration of any given time is relative to the 
time zone. If | tell my wife that the movie starts at 12:30pm, there is usually no 
ambiguity as we are "local" to each other. However, if a friend in London sends me a 
directory in a ZIP file and | look inside that directory, what time should | see the files as 
having been modified? If he modified a file and immediately sent it to me, he would say 
"| changed the file at 9:51pm" ... is that what | should "see" when | look at the file? The 
answer is no, | should see that he modified the file at "3:51pm" which would be my 
equivalent local time. 


Within an ESP32 environment, we can set an environment variable using the setenv () 
API. The variable is called tz and is used to define the local time zone in which the 
ESP32 is operating. From a time zone string, the ESP32 can then perform the 
additions or subtractions to determine the local time. Note that this is only possible if we 
record the time stamp of some data relative to an agreed convention ... and this is 
where Universal Coordinated Time (UTC) comes into the picture. UTC is the GMT time 
zone and is the value we get back from a call to time(). 


Let us break down the available functions supplied by ESP-IDF for time manipulation: 
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¢ Get the current time as atime t — time () 


* Convert atime t t0a struct tmignoring timezone — gmtime () 





¢ Convert atime t toa struct tmusing the timezone — localtime () 


* Converta struct tmtO atime t —mktime() 








* Converta struct tminto a string — asctime() 





* Convert atime t into a string — ctime(). Basically a convenience function for 


asctime (gmtime()). 


See also: 


Working with SNTP 
system_get_time 
Hardware Timers 
gettimeofday 
Timers in FreeRTOS 
asctime 

ctime 

gmtime 

localtime 

mktime 
settimeofday 

time 

times 

tzset 


Pulse Width Modulation - PWM 

The idea behind pulse width modulation is that we can think of regular pulses of output 
signals as encoding information in the duration of how long the signal is kept high. Let 
us imagine that we have a period of 1Hz (one thing per second). Now let us assume 
that we raise the output voltage to a level of 1 for 2 of a second at the start of the 
period. This would give us a square wave which starts high, lasts for 500 milliseconds 
and then drops low for the next 500 milliseconds. 


1 second 


1 
1/2 second 


Time 


Page 234 


This repeats on into the future. The duration that the pulse is high relative to the period 
as a whole allows us to encode an analog value onto digital signals. If the pulse is 
100% high for the period then the encoded value would be 1.0. If the pulse is 100% low 
for the period, then the encoded value would be 0.0. If the pulse is on for "n" 
milliseconds (where n is less than 1000), then the encoded value would be n/1000. 


Typically, the length of a period is not a second but much, much smaller allowing us to 
output many differing values very quickly. The ratio of the "on" signal to the period is 
called the "duty cycle". This encoding technique is called "Pulse Width Modulation" or 
"PWM". 


There are a variety of purposes for PWM. Some are output data encoders. One 
commonly seen purpose is to control the brightness of an LED. If we apply maximum 
voltage to an LED, it is maximally bright. If we apply % the voltage, it is about /% the 
brightness. By applying a fast period PWM signal to the input of an LED, the duty cycle 
becomes the brightness of the LED. The way this works is that either full voltage or no 
voltage is applied to the LED but because the period is so short, the "average" voltage 
over time follows the duty cycle and even though the LED is flickering on or off, it is so 
fast that our eyes can't detect it and all we see is the apparent brightness change. 
Internet articles suggest a frequency of between 300 and 1000 Hz are good values for 
LED dimming. 


Now let us look at how the ESP32 provides PWM support. Within the ESP32 there is 
hardware support for PWM supplied in a component called the "LEDC/PWM". It 
supplies 8 channels of output each of which can be controlled independently from the 
others. The ESP32 PWM functions are powerful but at first they can sound complex. 
The reality is that they actually aren't that hard and the power and flexibility within them 
is worth the learning. One just has to slow down and contemplate them for a bit. 


First, understand that there are four distinct timers. Think of an individual timer as 
"ticking along" counting up until it reaches a maximum number and then resets itself to 
zero and the story repeats. The time between resets (i.e. how long it takes to count to 
the maximum value) is the frequency value measured in Hz (things per second). For 
example, if we specified a frequency of 1Hz, it would take 1 second to count from 0 to 
the maximum value and then repeat. If we specified a frequency of 1000Hz (1000 
things per second), it would only take 1 millisecond to count from 0 to the maximum 
value. 
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LEDC_HSTIMERO_LIM 


Timer Value 





0 Time 


So what is this "maximum" value that | have been talking about? Each timer counts 
upwards and we can define how many "bits" in a number before it resets. Our choices 
when configuring a timer are 10, 11, 12, 13, 14 or 15 bits. These correspond to 
maximum values of 1023, 2047, 4095, 8191, 16383 and 32767. Pause here and think 
about the relationship between frequency and bit size of the counter. If we set our timer 
to have a frequency of 1Hz and set our bit size to be 12 bits, then it will take 1 second 
for our timer to count from 0 to 4095. If our bit size were 15 bits, it would take 1 second 
for our timer to count from 0 to 32767. It is important to realize that the frequency is 
how long it takes to count from 0 to the maximum number. If we have higher bit sized 
maximums, then we just have more "timer increments" ... but in the same frequency 
specified period of time. What we thus have is more "granularity" in the timings. 


Now that we have looked at the timer, lets turn our attention to the notion of a channel. 
A channel be thought of as the PWM output signal. When we define a channel, we 
specify which of the GPIO pins the signal will appear upon. We also specify which of 
the four timers we plan on associating with the channel. Since a timer defines a 
frequency, this defines the frequency (or period) of our PWM signal. Finally, and 
arguably most importantly, we define the duty cycle of the PWM output. This is the 
duration of a period that the PWM output signal will be high before it goes low. The 
value is supplied as a number of timer ticks and not a period of time and this is where 
folks can get lost. 


Think about the timer. It starts at 0 and counts upwards to its maximum value (as 
defined by its bit size) and then resets. The rate of counting upwards is specified by the 
frequency defined on the timer. If the frequency is 1Hz, then the timer takes 1 second 
to count from 0 to the maximum. The duty cycle value specifies the timer value after 
which the PWM output signal will flip from high to low. 


For example, imagine we wanted a PWM signal with a period of 1 second that is high 
for ‘4 of a second with a 10 bit granularity. We would set the frequency of the timer to 


Page 236 


be 1 Hz and the granularity of the timer to be 10 bits. This then says it takes 1 second 
for the timer to count from 0 to 1024. If we want the duty cycle of the PWM to be % of a 
second, then we want to switch the output signal % of the way through the timer count 
which would be 1024 * %4 = 256. 


LEDC_HSTIMERO_LIM © 


Timer Value 


256 





Time 


Output signal 


To use the LEDC/PWM functions we would follow this recipe: 


1. Set aLEDC timer. We do this by calling tedc_ timer config() passing ina 
ledc_timer config _t structure pointer. 


ledc_timer config _t timer conf; 
timer conf.bit num = LEDC TIMER 12 BIT; 
timer conf.freq hz = 1000; 
timer conf.speed_ mode = LEDC HIGH SPEED MODE; 
timer _conf.timer_ num = LEDC TIMER _0; 






































ledc_timer config(&timer_ conf); 


2. Seta LEDC channel. 


ledc_channel config _t ledc_conf; 
ledc_conf.channel = LEDC CHANNEL 0; 
ledc_conf.duty = 1024; 
ledc_conf.gpio_ num = 16; 
ledc_conf.intr type = LEDC_INTR_DISABLE; 
ledc_conf.speed_mode = LEDC HIGH SPEED MODE; 
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ledc_conf.timer_ sel = LEDC _TIMER_0; 
ledc_channel_ config(&ledc_conf) ; 


See also: 


Wikipedia: Pulse-width modulation 
ledc_channel_config 





ledc_timer_config 
Servos 


Automated PWM fading 

The hardware support for PWM in the ESP32 also includes an intriguing feature that 
relates to "fading". If we consider the duty cycle of PWM, we can think of it as the 
percentage of frequency that the signal is high vs low. So a 100% duty cycle will be 
constantly high and a 0% duty cycle constantly low with values in between giving us an 
"average" output over time. This can be used to "dim" LEDs. Now imagine that we 
wanted to change the brightness of the LED over time. Effectively we would be "fading" 
the brightness. For example, if we wanted to have the LED go from 100% brightness to 
50% brightness over 2 seconds, the brightness output might look as follows: 


100% 


Brightness 


0 1 2 
Time 
Since the value of the duty cycle corresponds to the brightness of the LED, then what 
we are talking about here is reducing the duty cycle value over time. Within the 
hardware of the ESP32 PWM, we can specify an initial duty cycle value and the amount 
that the duty cycle should be reduced by each configurable timer interval. 
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Analog to digital conversion 

Analog to digital conversion is the ability to read a voltage level found on a pin between 
0 and some maximum value and convert that analog value into a digital representation. 
Varying the voltage applied to the pin will change the value read. The ESP32 has an 
analog to digital converter built into it with a resolution of up to 12 bits which is 4096 
distinct values. What that means is that 0 volts will produce a digital value of 0 while the 
maximum voltage will produce a digital value of 4095 and voltage ranges between these 
will produce a correspondingly scaled digital value. 


One of the properties on the analog to digital converter channels is attenuation. This is 
a voltage scaling factor. Normally the input range is 0-1V but with different attenuations 
we can scale the input voltage into this range. The available scales beyond the 0-1V 
include 0-1.34V, 0-2V and 0-3.6V. 


Here is an example application using the APIs. What this example does is print the 
value read from the ADC every second. 


#include <driver/adc.h> 
#include <esp log.h> 

#include <freertos/FreeRTOS.h> 
#include <freertos/task.h> 
#include "sdkconfig.h" 


static char tag[] = "adcl"; 


void task _adcl(void *ignore) { 
ESP_LOGD(tag, ">> adcl"); 
adcl_config width (ADC_WIDTH 12Bit); 
adcl_ config channel atten(ADC1 CHANNEL 0, ADC ATTEN 6db); 
while(1) { 
int value = adcl_get_ voltage (ADC1 CHANNEL 0); 
ESP _LOGD(tag, "value: %d", value); 
vTaskDelay (2000/portTICK PERIOD MS); 
} 
vTaskDelete (NULL) ; 























} 


If we build out on a breadboard a circuit which includes a light dependent resistor such 
as the following: 
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ESP32 DevKitC 











Then when we change the amount of light falling on the resistor, we can see the values 
change as data is written in the output log. This can be used to trigger an action (for 
example) when it becomes dark. 


Open question: What is the sample rate of the ADC? 
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GPIO ADC Channel 
























































GPIO 32 ADC1_CH4 
GPIO 33 ADC1_CH5 
GPIO 34 ADC1_CH6 
GPIO 35 ADC1_CH7 
GPIO 36 ADC1_CHO0 
GPIO 37 ADC1_CH1 
GPIO 38 ADC1_CH2 
GPIO 39 ADC1_CH3 














Note that only a subset of ADC pins and functions are exposed. First, the supplied 
drivers expose only ADC1. The board layout of the ESP32-DevKitC only exposes some 
of the pins. Specifically, the following are exposed: abc1_ CHO, ADC1_CH3, ADC1_CH4, 
ADC1_CH5, ADC1_CH6 and ADC1_CH7. 


See also: 


adc1_config_channel_atten 
adc1_config_width 

adc1_get_voltage 

Wikipedia: Voltage divider 

YouTube: Analog to Digital with ESP32 
YouTube: Electronics Basics #27: ADC 








Sleep modes 

If the ESP32 device is constantly on, then it is constantly consuming current. If the 
power source is unlimited, then this need not necessarily be an issue however when 
running on batteries or other finite supply, we may need to minimize consumption. One 
way to achieve this is to suspend the operation of the device when not in use. When 
the device is suspended, the notion is that consumption will be reduced. There are 
three defined sleep modes. These are called modem-sleep, light-sleep, deep-sleep. 
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By looking at the following table we can get a sense of the abilities in each of these 
three modes: 



































Function Modem Light Deep 
WiFi off off off 
System Clock on off off 
Real Time Clock on on on 
CPU on pending off 
Current consumption 15mA 0.5mA 20HA 





The modem-sleep can only be used when the ESP32 is in station mode connected to 
an access point. The application of this mode is when the ESP32 needs to still perform 
work but minimizes the amount of wireless transmissions. 


The light-sleep mode is the same as modem-sleep but in this case the clocks will be 
suspended. 


In deep-sleep mode, the device is really asleep. Neither CPU nor WiFi activities take 
place. The device is to all intents and purposes off ... with one exception ... it can wake 
up at a specified regular interval. 


To enter deep sleep mode, we can call system deep sleep(). This can be supplied with 
a suspension time. The device will go to sleep and after the interval has elapsed, the 
device will wake up again. In addition to having a timer, we can also awake from a deep 
sleep by toggling the value of a signal on a pin. 


Write about ... 
esp_deep_sleep_pd_config 
esp_deep_sleep_ enable_ext0_ wakeup 
esp_deep_sleep enable_ext1_wakeup 


esp_deep_sleep_ start 


esp_deep_sleep_enable_timer_wakeup 
esp_deep_sleep 

RTC_DATA_ATTR — Specify memory is RTC memory 
How do we determine WHY we woke up? 


See also: 
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YouTube: ESP32 #18 — Deep sleep API and how to wake up 





Security 

The ESP32 has the ability to store the password used to connect to the access point in 
memory. This means that if one were to physically compromise the device (i.e. steal it) 
then they could, in principle, dump the flash memory and retrieve your password. You 
could choose not to cache the password in the clear in flash but instead have your 
applications "decode" an encoded version that is saved in the flash memory ... this 
would prevent an obvious retrieval through a simple memory grab. The encoding 
scheme could be a simple XOR against a magic number (either hard-coded or your own 
MAC address). 


Working with flash memory 
Flash memory provides a non-volatile repository of information that survives a power 
cycle of the device. 


Data contained within flash is stored in units of sectors which are 4096 bytes in size. To 
write data we can call spi flash write. To read data we call spi flash read. 


Since writing to flash is performed in units of 4096 bytes, we can not change a single 
byte by just over-writing it, instead we must retrieve the whole sector, erase the sector 
and then write back the sector with the changed content. This can take some time to 
complete and because of this, we may find that a failure is more likely to occur (eg. a 
loss of power). If a failure occurs after we have erased a sector or during the re-write of 
the sector, it should immediately become apparent that we will result in an overall 
corruption of data. 


Data reads and writes have to be 4 bytes aligned within flash. 


The ESP32 has to be instructed about the size of the flash memory available to it. 
Attempting to use flash memory addresses that differ from the expected size of flash 
memory available can result in unexpected results. 


When using esptool.py, the --flash_ size flag can be supplied. For esptool-ck, the 
corresponding flag is -bz. 


The memory map for flash is flexible. A 1 MByte flash has an address range of 
0x00 0000 - OxOF FFFF 
The bootloader loads at 0x00 1000. 


The partition table loads at 0x00 8000. 
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NVS loads at 0x00 9000 to 0x00 EFFF Which is 24K. 





ESP32 data lives at 0x00 F000 to 0x00 FFrFF Which is 4K. 


The single app loads starting at 0x01 0000. Ona typical 4MByte flash space, this would 
then end at 0x3F FFFF. 









































Address Description 
0x00 1000 | Bootloader 
0x00 ???? Unknown 
0x00 8000 | Partitiontable _—| 
0x00 ???? Unknown 
0x00 9000 NVS 
0x00 EFFF 

0x00 FOOO 

Ox00 FFFF 

0x01 0000 App 

See also: 


. spi_flash_erase_sector 
spi_flash_read 
. Cesanta: ESP8266, flash and alignment 





Working with RAM memory 
We can allocate memory using malloc() OF zalloc(). The first function allocates and 
returns memory and the second does exactly the same but zeros the memory before 
returning. When your application logic no longer needs the memory, it can return it back 
to the heap with free (). To determine how much heap size is available, we can call 

sp get free heap size(). Once we have the memory pointer to allocated storage, we 
can start to manipulate it through a series of memory commands. The memset () 
command will set a block of memory to a specific value. The memcpy () will copy a block 
of memory to a different block. The bzero() function will set the values of a block of 
memory to zero. 








Memory on the ESP32 is made up of a number of components. We have: 
¢ data 


* rodata 
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* bss 
* heap 
The values of these can be found through the system print _meminfo() function. 


When the ESP32 needs to read an instruction from memory in order to execute it, that 
instruction can come from one of two places. The instruction can be in flash memory 
(also called irom) or it can be in RAM (also called iram). It takes less time for the 
processor to retrieve the instruction from RAM than it does from flash. It is believed that 
an instruction fetch from flash takes four times longer than the same instruction fetched 
from RAM. However, on the ESP32 there is less RAM than there is flash. What this 
means is that you are far more likely to run out of RAM before you run out of flash. 
When writing normal applications, we shouldn't fixate on having instructions in RAM 
rather than flash for the performance benefit. The execution speeds of the ESP32s are 
so fast that if the cost of retrieving an instruction from RAM is blindingly fast then 
retrieving an instruction from slower flash is still blindingly fast. 


There are however certain classes of instructions that we might wish to place in RAM 
rather than flash. Examples of these are interrupt handlers where the time spent in 
these should always be as short as possible and also function that write to flash. 


When we define C functions, we can add an attribute by the name of 

ICACHE FLASH ATTR. What this does is place this function in the flash memory address 
space as opposed to RAM. Specifically, flagging a function with IcAcHE FLASH ATTR 
tags it as being in the ".iromo.text" section of code. 














Note: From a raw technical perspective, ICACHE FLASH ATTRisa #define that maps to: 





__attribute_ ((section(".irom0.text") )) 








The mapping of RAM is 























Ox3FFB 0000 Data Ram 
Ox3FFF 0000 256K 
0x4008 0000 Instruction Ram 
0x400A 0000 128K 
See also: 

esptool.py 


gen_appbin.py 
Wikipedia — Data segment 
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RAM Utilization 

As we write applications using the ESP-IDF, we will likely perform repeated tasks such 
as creating sockets, creating FreeRTOS tasks and other items. Since anytime we 
create something that has state, we will be consuming RAM, the question arises of "how 
much RAM"? The amount of RAM used for common tasks governs just how many 
instances of that task we can perform without relinquishing previously used memory. 


An easy way to determine the current amount of free memory is to use the 

sp get free heap size() function. This returns the number of free bytes of RAM on 
the heap. As we use more RAM, the value returned by this function decreases. If we 
wish to measure how much RAM a particular function might use, one way would be to 
measure the free RAM before the call and then measure it again after the call and the 
difference is some indication of how much might be used. 








As a base line, after we start an ESP32 application and connect to an access point, | 
find that the amount of RAM reported back is 191452. In these notes, I'll round that to 
the nearest 1000 bytes and refer to this as "K" ... for example 191K (not to be confused 
with common "K" meaning 1024). 


Let us start by looking at creating a FreeRTOS task. We commonly use 
xTaskCreatePinnedToCore () for that purpose. The 3 parameter to that function is the 
stack that is allocated for the new task. This is carved up front from the heap when the 
task is created. As you can immediately see, creating a stack far larger than needed 
will immediately waste RAM. 


Next, lets look at static RAM usage. This is storage data that is read/write but is 
declared as static in C application. For example, 


static char buffer[10*1024]; 
void myFunc() { 


} 
In the above, buffer is readable and writeable ... but does NOT reduce the heap size. 


However not declaring as static, DOES reduce the heap size: 


char buffer[10*1024]; 
void myFunc() { 


} 
What about the following: 


void myFunc() { 
char buffer[10*1024]; 
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} 


In this case, the storage is taken from that of the FreeRTOS task. So the global heap 
does not decrease but the amount of free space of the FreeRTOS task will diminish. 


Turning to sockets based APIs. The act of creating a listening socket seems to only 
cost ~700 bytes. Accepting a new connection which itself creates a new socket again 
only appears to cost about 700 bytes. 


esp_get_free_heap_size 


EFUSE 

Think of the classic (old?) household fuse. When too much current passes through it, 
the filament wire inside gets too hot and melts through thus breaking the circuit and 
electricity stops flowing. If we assign the flow of electricity the value "1" and the 
inability to flow electricity the value "0", we have a simple boolean value that we can 
detect. The concept of an EFUSE in the ESP32 is a set of bits that can be electrically 
set one time. Imagine they have a default value of "1", we could select 8 bits and for 
some of them, pass enough current through them to "blow the fuse". This doesn't harm 
the ESP32 ... its what these EFUSEs were designed to do. As a result, we now have 8 
bits of data some of which are "1"s and some of which are "0"s ... in effect ... a byte of 
data that we set to a fixed value in the hardware. Realize that setting an EFUSE to 0 is 
a one time operation, you can't subsequently change it back to 1 ... however it does 
afford us a useful capability. We can imagine ESP32s that have electrically "hard 
coded" values pre-assigned at manufacturing or distribution time. These could be 
device identifiers or keys for encryption. Because the values are burned into the device, 
they can't subsequently be altered or tampered with. 


The ESP32 has 1024 bits of EFUSE of which 256 are reserved for the of Espressif for 
purposes such as the network MAC addresses and chip configuration. However, this 
still leaves 768 distinct bits at your disposal. 


For the tinkerer, there is unlikely to be a compelling reason to use EFUSEs, but for the 
production customer, this is yet another feature you can choose to leverage. 


Button press detection 
Button press detection is one of the simplest circuits there is. A schematic may look as 
follows: 
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What we see here is that when the button is pressed, the GPIO 25 goes high. When 
the button is not pressed, there is an open input to GPIO 25. As such, we want to flag 
GPIO 25 as having a pull-down associated with it so that it has a default signal of low. 


Now we can define an interrupt handler to GPIO 25 that will be called wnen GPIO 25 
transitions from low to high. Unfortunately, this is not enough. When a button is 
pressed, it usually "bounces" for a very small period. This will be interpreted as a series 
of transitions and hence a series of interrupt handler events. What we want to do is 
introduce a debounce handler. One way to achieve this is not to trigger our processing 
when the signal transitions from low to high but to trigger our processing when the 
signal transitions from low to high and the last transition from low to high was at least 
50-100 msecs ago. When bounces happen, they are usually much shorter than those 
time periods and can be eliminated. 


Here is an example application which illustrates a GPIO interrupt handler: 


include <driver/gpio.h> 
include <esp_log.h> 

include <freertos/FreeRTOS.h> 
include <freertos/queue.h> 
include <freertos/task.h> 


include "c_timeutils.h" 
include "sdkconfig.h" 








static char tag[] = "test _intr"; 
static QueueHandle t ql; 


#define TEST GPIO (25) 
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static void handler(void *args) { 
gpio_num_t gpio; 


gpio = 


TEST GPIO; 








xQueueSendToBackFromISR(ql, &gpio, NULL); 


} 


void testl_task(void *ignore) { 


Struct 





timeval lastPress; 


ESP_LOGD(tag, ">> testl_task"); 


gettimeofday(&lastPress, NULL); 


pio_num_t gpio; 
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pioConfig.mode = GPIO MODE INPUT; 
pioConfig.pull_ up _en = GPIO PULLUP DISABLE; 
pioConfig.pull down _en = GPIO PULLDOWN_ ENABLE; 
pioConfig.intr type = GPIO_ INTR_POSEDGE; 
pio_config(&gpioConfig) ; 


1 = xQueueCreate(10, sizeof (gpio_num_t)); 





fig t gpioConfig; 
-pin_bit_mask = GPIO SEL 25; 









































gpio_install_isr service(0); 


gpio_isr handler add(TEST GPIO, handler, NULL); 





while(1) { 


ESP _LOGD(tag, "Waiting on queue"); 





Bas 











ESP_ 





Type t re = xQueueReceive (ql, &gpio, portMAX DELAY) ; 





OGD(tag, "Woke from queue wait: %d", rc); 





struct timeval now; 


get 
if 


} 


las 


} 


timeofday(&now, NULL); 
(timeval durationBeforeNow(&lastPress) > 100) { 


ESP_LOGD(tag, "Registered a click"); 





tPress = now; 


vTaskDelete (NULL) ; 


GPS 


The world is a sphere (hopefully that isn't news to you). We can specify a point on the 
Earth through a coordinate system known as latitude (lat) and longitude (Ing). Givena 
lat/Ing coordinate, we know where we are. The Global Positioning System (GPS) is a 

technology that allows a GPS receiver to determine its own lat/Ing coordinates. 


Given a pair of coordinates, for example one coordinate that says where a device is and 


a second 
calculate 
compass 
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coordinate saying (for example) where we want to eventually be, we can 
some interesting data such as how far away are we from the target and what 
bearing we need to head to get there. 


There are many applications of GPS and it has entered the popular domain. Most cell 
phones now have in-built GPS receivers such that they can display a map showing your 
current location. Combine that with a database of driving directions and we have real- 
time route planners where we mount either a dedicated GPS receiver or a cell phone on 
our car dashboards and provide destination details and the devices tell us the turns to 
make. 


The Global Positioning System (GPS) is a set of satellites in orbit. They are continually 
transmitting a very precise time signal. If we have a suitable receiver, we can receive 
the time signals from some number of those satellites that are over head at any given 
time. Since the speed of radio transmission is constant and not instantaneous and each 
satellite is producing an extremely accurate and synchronized time signal, then a signal 
clock pulse emitted by all satellites at exactly the same time will be received at very 
slightly staggered times by the receiver as a function of the distance that the signal had 
to travel through space. This is the same as the distance that the satellite was from the 
receiver. By receiving enough signals from a sufficient number of distinct satellites and 
by using complex mathematics, the receiver can then triangulate its own position and 
thus know where it is on the surface of the Earth. 


Putting that in perspective, an electronic module can determine physically where it is. 
Such modules are now common within your cell phone and within many car 
dashboards. They are often used in conjunction with mapping software to provide a 
real-time map showing your location. The accuracy of GPS is commonly about 4 
meters. 


Devices can be picked up for about the $12 mark. The unit | worked with is called the 
GY-GPS6MV2 which is based on the u-blox NEO-6m. The pins on this breakout board 
are vcc, gnd, RX and TX. This is 5V device. As such, you must use a level shifter or 
voltage divider between the TX pin of the GPS and the RX pin of the ESP32 as the 
ESP32 can't accept a 5V signal input. 


Since it is a UART device, we can test this on a regular PC. If we connect a serial port 
terminal, we can watch the data be received. The data that comes across is in NMEA 
format (National Marine Electronics Association). There are various NMEA reader 
applications freely available which can format the data. The baud rate for the device 
defaults to 9600 bps. 


To test the data, you should really be out-doors or otherwise have an un-obstructed 
view of the sky. Testing in the interior of a building is basically fruitless as the GPS 
signals will not penetrate and you will have learned nothing. 
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The device has an LED on the circuit that illuminates (flashes green) when a lock has 
been made. 


Here is a sample that reads input from GPIO34 which is connected to the GPS TX: 


#include "esp log.h" 
#include "driver/uart.h" 


static char tag[] = "gps"; 
void doGPS() { 




















ESP LOGD(tag, ">> doGPS"); 

uart_config_ t myUartConfig; 

myUartConfig.baud_rate = 9600; 

myUartConfig.data bits = UART DATA 8 BITS; 
myUartConfig.parity = UART_ PARITY DISABLE; 
myUartConfig.stop bits = UART STOP BITS 1; 
myUartConfig.flow ctrl = UART_ HW _FLOWCTRL DISABLE; 
myUartConfig.rx flow _ctrl_ thresh = 120; 


uart_param_config(UART NUM 1, é&myUartConfig) ; 


uart_set_pin(UART NUM _1, 
UART_PIN NO CHANGE, // TX 
34, // RX 
UART_PIN NO CHANGE, // RTS 
UART_PIN NO CHANGE // CTS 





Bi BJ 





uart_driver install (UART_ NUM 1, 2048, 2048, 10, 17, NULL); 


unsigned char buf[100]; 
int size; 
while(1l) { 
size = uart_read_bytes(UART_NUM_ 1, buf, sizeof(buf), 1000/portTICK PERIOD MS) ; 
ESP _LOGD(tag, "Bytes read = %d", size); 
if (size >0) { 
ESP LOGD(tag, "%.*s", size, buf); 
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GPS decoding 

An open source project on Github called "minmea" provides an excellent parsing library 
for the protocol generated by these GPS devices. If we read a line at a time from the 
GPS device and pass that into the parsing routines, we can get data including position, 
speed and visible satellites. The library compiles 100% cleanly with ESP-IDF as long 
as one adds: 





CFLAGS+=-Dtimegm=mktim 


to the component .mk used to build from the source. The sample snippets supplied with 
the project proved to be more than sufficient to get a solution going in no time. 


At a high level, the protocol exposed by the GPS device is called NMEA 0183. It is 
composed of one line at a time where each line is considered to be a "sentence". The 
sentence starts with a designator describing the types of sentence it represents. The 
minmea parser has support for the following types: 


* rmc — Time, latitude, longitude, speed, track, date 

* cca—Time, latitude, longitude, GPS quality, satellite count, altitude 
¢ csa—<Active satellites 

* cLL— Latitude, longitude, time 

* cst — Error measurements 

* csv — Satellites in view 

¢ vtc— Track and speed 


See also: 


Github: cloudyourcar/minmea 
NMEA Revealed 





Temperature and pressure - BMP180 

The BMP180 module can be found on eBay for less than $2.00. This device provides 
both temperature and barometric pressure readings via an I2C bus. It is less expensive 
than the DHT22 but replaces humidity for air pressure measurement. Arguably, the 
BMP'180 is also easier to use as it does not require as finicky data stream timings. 
Although common, this device has been superseded by the manufacturer with a later 
model called the BMP280. 
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This is a 3V device. The I2C address of the device is 0x77. 


The I2C commands to read the device are described in detail in the data sheet. Ata 
high level, we read out a series of EEPROM registers and then ask for both the 
temperature and pressure. The values returned for these later values need to them be 
arithmetically combined with the EEPROM registers using some equations and the 
result will be two outputs. A temperature in °C and an air pressure in Pa. 


The pin out of the some device types are: 


























Pin Label Description 
1 3.3 Not used 

2 SDA I2C SDA 

3 SCL I2C SCLK 
4 GND GND 

5 VCC 3.3V 








While others have the pin out of: 


























Pin Label Description 
1 VIN 3.3V 

2 GND GND 

3 SCL I2C SCLK 
4 SCA I2C SDA 
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At the driver level, here are the low level details. First we read compensation 
parameters through I2C. The parameters are identified in the data sheet as 16 bit 
integers (MSB) read from the following I2C registers: 















































Parameter C Type Registers 
ACI short OxAA, 0xAB 
AC2 short OxAC, 0xAD 
AC3 short OxAE, OxAF 
AC4 unsigned short OxBO, 0xB1 
ACS5 unsigned short 0xB2, 0xB3 
AC6 unsigned short 0xB4, 0xB5 
Bl short OxB6, 0xB7 
B2 short OxB8, 0xB9 
MB short OxBA, 0xBB 
MC short OxBC, 0xBD 
MD short OxBE, OxBF 








My understanding (loosely) is that when an instance of a BPM180 is manufactured, 
there can be slight variances in the construction from one batch of devices from 
another. These variances are anticipated and have to be accommodated. As sucha 
set of mathematical compensation values are written into an EEPROM contained within 
the device which provide the details of the specific variants for this exact device. When 
we ask the device for temperature and pressure values, we then have to also read the 
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compensation values and apply some mathematics using those plus the obtained 
readings to achieve the final numbers. Fortunately, we don't have to worry about the 
actual underlying math, these have been worked out for us by the device designers. 
However, in our software, we do have to actually perform the math using the 
compensation values and the sensor read data. The details of the math can be found in 
the device data sheets and also from the many examples in Github that have already 
implemented the correct algorithms. 


To read a register we perform: 


<Start> <Address + WRITE> <Register> <Stop> 
<Start> <Address + READ> <Read MSB> <Read LSB> <Stop> 


See also: 


Data sheet 

Sparkfun — BMP180 Barometric Pressure Sensor Hookup 
BMP180 12C Digital Barometric Pressure Sensor 

Github: Sparkfun/BMP180 











Using the Arduino APIs 

Adafruit provide an Arduino library for interacting with the device. This is part of their 
unified sensor series. It has been tested with the Arduino environment running on the Pi 
and found to work without issue. Stay away from the similarly named project called 
Adafruit-BMP085-Library as it appears to be buggy. 





See also: 


Adafruit Unified Sensor Driver 
Adafruit Unified BMP085/BMP180 Driver 








NeoPixels 


NeoPixel theory 

NeoPixels are LEDs that are driven by a single data line of high speed signaling. Most 
NeoPixels have a +ve and ground voltage source as well as a data line for input and a 
data line for output. The output of one NeoPixel can be fed into the input of the next 
one to produce a string of such LEDs. The input data to the LED is a stream of 24 bits 
of encoded data which should be interpreted as 8 bits for the red channel, 8 bits for the 
green channel and 8 bits for the blue channel. Each channel can thus have a 
luminance value of between 0 and 255. By mixing the values for each of the channels 
together, you can color an LED to any color you may choose. After sending in a stream 
of 24 bits, if we send in a second stream of 24 bits quickly after the first stream, the 
second stream is "pushed" through to the next LED in the chain. This can be repeated 


Page 256 


as far as desired. If we pause sending in data, the current values are "latched" into 
place and each LED them remembers its own value. 


The timings of the data signals for these LEDs can be quite tricky but fortunately great 
minds have already built fantastic libraries for driving them correctly so we need not 
concern ourselves with these low level timings and can instead concentrate on devising 
interesting projects and purposes to which the LEDs can be placed. There area 
number of different types of these LEDs with the most common ones being known as 
WS2811, WS2812 or PL9823. 


NeoPixels are usually 5V devices but check the specs carefully. Since NeoPixels draw 
a lot of current (60mA each), do not try and power them from low current sources. You 
also need to be careful when sending signals into them and getting their polarity correct. 
If you mess up, they are unforgiving. | recommend buying more instances that you will 
need in case you make a mistake. 


"/ 
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The eight piece strip is labeled CUMCU-2812-8. It has 4 pins at each end of the strip 
labeled: 





Label Description Color 
GND Ground. 


DIN/DOUT One side is DIN the other DOUT ... this means that the strip is polarized. These are 
the control data input and output lines. 


4-7VDC Source voltage. 
GND Ground. 


























The data is sent as 24 bits in Green/Red/Blue order (GRB). Note that this is NOT RGB. 
The format of the data uses NZR (Non-return-to-zero) encoding. 


Specifically, the logic 0 and logic 1s are encoded as following. 
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0.35us 
Logic 1: pe 


Both bits correspond to a transition from high to low to high again but the duration at 
which they are held indicates the encoding of a 1 or 0. 


The data send to an individual device is 24 bits corresponding to 8 bits of color data for 
each of the RGB components. The 8 bits identify the brightness of each of the channels 
with 1 being lowest and 255 being brightest. 


Various diagrams show the timing as follows: 


Sequence chart: 


TOL 
0 code fof 
TOH 
T1H 
RET code [+71 __+] 


Various data sheets show different timing values in micro seconds: 




















Device TOH TOL TO T1H TIL T1 
WS2811 0.5 2.0 23 1.2 1.3 25 
WS82812 0.35 0.8 1.15 0.7 0.6 1.3 
WS2812B 0.4 0.85 1.25 0.8 0.45 1.25 
PL9823 0.35 1.36 1.71 1.36 0.35 1.71 


























As we see, for a WS2812B, the "width" of a bit is about 1.25 microseconds. For a full 
pixel, this would be 24 bits or 30 microseconds. Thinking of it another way, that would 
be over 33,000 pixels that could be updated per second. 


The data is sent high bit first. 


For testing circuits, | like to use PL9823. These can be had on eBay for between 25 
cents and 35 cents each. It is physically easy to work with and in the event of a design 
or assembly error, they are cheap enough to shrug off damage and throw away ones 
you damage or break. 
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F8 9823 LED Chip 


See also: 


WS2812 Data Sheet 

PL9823 Data Sheet 

Use a $1 ATTiny to drive addressable RGB LEDs 

Adafruit NeoPixel Uberguide 

NeoPixels Revealed: How to (not need to) generate precisely timed signals 














NeoPixels and the ESP32 

If we take the WS2812 as an average device, we see that we need to create timings on 
the order of 400ns. That is much too short an interval to perform in code logic so we will 
need hardware support to achieve the task. Fortunately, the RMT driver gives us 
exactly what we need. If we look at the base clock, we find that it has a maximum 
resolution of 80MHz which is a resolution of 12.5ns. In fact if we use a divisor of 8 we 
then have a granularity of 100ns which puts us right on target. Thus to send a 0, we 
would transmit high for 400ns and low for 800ns and to send a 1 we would transmit high 
for 800ns and low for 500ns. A latch is low for 50us (50,000ns). 


A sample C++ class for driving NeoPixels from the ESP32 is available here: 


https://github.com/nkolban/esp32-snippets/tree/master/hardware/neopixels 





See also: 


RMT — The Remote Peripheral 


LED 7-Segment displays 

The 7-Segment display is an LED device that is composed of 7 line segments that can 
be arranged to display numbers. There is also an eighth LED that is used to display a 
decimal point. The makeup of the segments are shown in the following diagram: 
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Although a seven segment display looks "quite dated" they should not be discounted. If 


what one wants to do is show a numeric value that can be read from a distance and 
which is very cheap to use, then this device may be just perfect. 


It is common to see 7-segment displays used in conjunction with the MAX7219 or 
MAX7221 ICs. These ICs know how to drive up to eight multiplexed 7-segment 
displays with data received over an SPI bus. As such, the ESP32 can send in an SPI 
signal and these devices can easily display the results. 


See also: 


Wikipedia — Seven-segment display 





MAX7219/MAX7221 - Serial interface, 8-digit, led display drivers 

The MAX7219 and MAX7221 are ICs that can drive up to eight digits of 7 segment 
displays or drive an 8x8 matrix of LEDs. The LEDs should be common cathode. The 
device works using the SPI protocol. 


This is a 5V device. A3.3V device known as the MAX6951 is also available. Note that 
the device is input-signal only. As such, there should be no issues connecting it to any 
of your ESP32 pins. 


The physical layout of the IC looks as follows: 


DOUT 
SEG D 
SEG DP 
MAXIMA SEG E 


MAX7219 SEGC 
MAX7221 


Ve 
ISET 

SEG G 
SEG B 
SEG F 
SEGA 





CLK 





Place a 10uF electrolytic and 0.1uF ceramic as close to the device as possible. 


For 7-Segment displays, these should be common cathode. 
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The pin out of the IC is shown in the next table. 




















































































































Name Pin Description 

DIN 1 Serial data input (MOSJ). Data loaded on clock rising edge. 

DIGO-DIG7 2, 3, 5-8, 10, 11 | Connections to each of the eight digits. 

GND 4,9 Both ground pins must be connected. 

es 12 Chip select. Data is loaded into serial register while CS is low and 
latched on CS rising edge. Unlike other SPI devices where you can leave 
the CS enabled, this device needs to actively control the CS. 

CLK 13 The clock for the serial data, 

SEGA-SEGG, DP | 14-17, 20-23 Connection to each of the eight segments in a digit. 

ISET 18 Connect to Vpp through a resistor to set peak segment current. The 
resistor values are shown in a following table. The resistor is referred to 
as Rsgr. The current sent to a segment is 100 times the current entering 
ISET. 

Vop 19 5V 

DOUT 24 Serial data output for daisy chaining. 

Data format: 

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 
x x x x Register Address Data 

Registers 
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Name Bits Description 
Shutdown 0b1100 (Oxc) Should the device shutdown the display 
¢ 0 -Shutdown. In shutdown mode the display is blanked. 
¢  1—Normal 
Decoding 0b1001 (0x9) | How is decoding performed? 
* 0x00 —No decoding for digits 7-0 
¢ Corresponding bit on — Code B decode for digit (0-9, E, H, L, P and '-') 
Intensity 0b1010 (Oxa) The brightness of the display 
0000 — 1111 with 0000 being minimum and 1111 being maximum. 
Scan Limit 0b1011 (Oxb) Controls how many digits are to be included in the scan multiplexing. 
* 0b0000 — Digit 0 
*  0b0001 — Digits 0, 1 
*  0b0010 — Digits 0, 1, 2 
¢  0b0011 — Digits 0, 1, 2,3 
*  0b0100 — Digits 0, 1, 2, 3, 4 
¢  0b0101 — Digits 0, 1, 2, 3, 4,5 
*  0b0110 — Digits 0, 1, 2, 3, 4, 5, 6 
¢  0b0111— Digits 0, 1, 2, 3, 4,5, 6, 7 
Display Test | 0b1111 (Oxf) Test the display. 
* 0-—Normal operation 
* 1-—Test mode 
No-Op 0b0000 (0x0) ‘| Don't perform any task. Useful for passing data through the device to a daisy 
chained instance. 
Digit 0 0b0001 (0x1) Set the value for digit 0. 
Digit | 0b0010 (0x2) Set the value for digit 1. 
Digit 2 0b0011 (0x3) Set the value for digit 2. 
Digit 3 0b0100 (0x4) Set the value for digit 3. 
Digit 4 0b0101 (0x5) Set the value for digit 4. 
Digit 5 0b0110 (0x6) Set the value for digit 5. 
Digit 6 0b0111 (0x7) Set the value for digit 6. 
Digit 7 0b1000 (0x8) Set the value for digit 7. 





The value of the rs! 





ET resistor can be seen in the following table: 




















LED Forward Current |1.5V 2.0V 2.5V 3.0V 3.5V 
10ma 66.7k 63.7k 59.3k =| 55.4k 51.2k 
20ma 29.8k 28.0k 25.9k | 24.5k 22.6k 
30ma 17.8k 17.1k 15.8k 15.0k 14.0k 
40ma 12.2k 11.8k 11.0k 10.6k 9.7k 
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Anodes of the LEDs must be connected to the sEcx lines while cathodes must be 
connected to the picGx lines. 


There are boards available which have MAX7219's already mounted and ready for work 
including 8x8 LED matrices. These are much easier to work with than wiring together a 


rats-nest of links. The boards cost less than $2 an instance. The pin out from the board 
are: 























Pin Label Description 
1 Vcc +ve 

2 GND Ground. 

3 DIN Data in. 

4 CS Chip Select. 
5 CLK Clock. 














Here is an image of such a board: 





In addition to these 7-segment LEDs, there are also 8x8 matrix boards that use the 
same MAX7219 and have the same pin outs. 
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See also: 


MAX7221 Home Page 

Drive MAX7219/MAX7221 with common anode displays 

Arduino — The MAX7219 and MAX7221 LED drivers 

Github: Arduino — wayoda/LedControl library 

Instructables — 16x8 LED dot matrix with MAX7219 module 

YouTube — ESP32 Technical Tutorials: Driving the MAX7219 

YouTube — BrainyBits - How to use MAX7219 Dot LED matrix with Arduino 

YouTube — Scrolling text using the MAX7219 and an Arduino 

YouTube — Arduino tutorial: LED Matrix red 8x8 64 Led driven by MAX7219 (or MAX7221) and Arduino Uno 


























The U8g2 library 

Available on Github is a rather good library for driving monochrome displays. The 
library is called U8g2. See the links for the web page. There are actually two libraries. 
One is called U8g2 which requires a memory buffer in the ESP32 to hold the raster of 
the image and a second library called U8x8 which is text only and needs no raster 
buffer. In order to work with the library, you need to know the controller type of the 
graphics device plus the size of the display in pixels. There are separate constructors 
for each of the distinct supported combinations. The supported combinations can be 
found here. 


The primitive drawing commands are bound to C functions and include filled rectangles, 
frames, circles, ellipses, text and much more. Tests | have performed show that it 
worked fine with an SSD1306. 


When we think of a display, we should think of its as a rectangular array of pixels of a 
fixed width and height. It is common to keep a data representation of what should be 
shown on the display in RAM and this is known as a frame buffer. A change in the RAM 
which is then pushed to the display causes an update of the display. If we set a bit in 
the frame buffer to be 1 and then cause the frame buffer to be displayed, the 
corresponding pixel will illuminate. 


Page 264 


The manufacturers of distinct displays have chosen distinct technologies for 
representing pixel data and how that pixel data is pushed to the displays. For example, 
some vendors have 8 bits of data as the vertical set of pixels top to bottom while others 
have them going from left to right. The U8g2 library attempts to normalize the story by 
providing logical primitives that are then mapped to the correct data streams and frame 
buffer updates appropriate for the specific device. 


The U8g2 library is MCU agnostic. That means that it knows nothing about ESP32 and 
everything about displays. To have the library work with the ESP32 we need a 
hardware abstraction level or HAL. The HAL maps logical requests issued by the library 
such as set a GPIO pin from high to low or send data via SPI to the actual APIs that are 
needed by the target platform, in our case an ESP32. Aset of HAL routines for the 
ESP32 has been written. These routines can be compiled and linked with the U8g2 
library and the ESP32 application to provide ESP32 support. 


See also: 


Github: olikraus/u8g2 


U8q2 API reference 
YouTube — ESP32 Technical Tutorials: Displays and the U8qg2 library 








LCD display - Nokia 5110 - PCD8544 

This little LCD screen has a resolution of 84x48 pixels and can be picked up on eBay for 
about $3. The underlying IC is the PCD8544 but it is also known as the Nokia 5110. 
The device is driven by an SPI interface. Since the device is input (to the device) only, 
we need not be concerned with overloading ESP32 input pins. 





The pins on the board are: 
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Description 

Vcc — 6V —8.5V 

GND 

SCE / CS — Chip enable. A low edge indicates start of data transmission. 
RST — Reset the device. Active low. 

D/C — Input is Data (1) or command (0). 

DN <MOSI> — The SPI MOSI 

SCLK — The SPI clock. The maximum permissible clock speed is 100KHz. 
Backlight LED 


























OPN DN] MIR] WIN] RR 














The data sheet explains well the sequence of commands that need to be sent to drive 
the display however, as always should be the case, you should look to be leveraging 
what already exists rather than re-inventing for the sake of it. The fantastic folks at 
Adafruit with their Adafruit GFX graphics library have provided an Arduino library for 
working with the device. This library has been ported to work with the ESP32. As 
such, all you need are copies of those libraries and you are ready to go. 


An example set of pin mappings might be: 

















See also: 


Data Sheet 
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OLED 128x32, 128x64 - SSD1306 

Another screen device that is readily available are the small OLED displays. These are 
based on an IC called the SSD1306 and can be found on eBay using that phrase as a 
search. The price for an instance seems to range between $5 and $12. 


The device can operate at either 3.3V or 5V. 





The typical resolution is either 128x32 or 128x64 pixels. Ata 6x8 character resolution, 
this would give us 4 or 8 rows of 21 (and a bit) columns (128 pixels/6 pixels per column 
= 21.333) . 


The pin out on this device is 





Pin Description 

GND — Ground 

VCC — 3.3v or 5.0V 
DO — Clock 

D1 —MOSI 

RES — Reset 

DC — Data / Command 
CS — Chip Select 























WED] A] BRL Wl nl] re 














The device can support a variety of protocols including 3 or 4 wire SPI and I2C. 
Depending on the model / variety of the board it you obtain, it is likely that it will be 
physically configured in one particular mode. Examine the board and the associated 
documentation. 


Again the excellent Adafruit folks have produced libraries for the Arduino which have 
been ported to the ESP32. 


A potential wiring diagram is as follows: 
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This display has also been tested with the U8g2 lib and worked as advertised. 
See also: 


The U8g2 library 

$SD1306 Data Sheet 

Github — Adafruit SSD1306 

Adafruit - Monochrome OLED breakouts 
ESP32 - Adafruit_SSD1306-Library 














Ambient light level sensor - BH1750FVI 

An interesting little module incorporating the BH1750FVI (aka GY-302) is available from 
a number of suppliers on eBay. Simply put, this device measures the amount of light 
falling upon it and returns a measurement of that value. While that can be done through 
a simple light dependent resistor and an analog to digital converter, this device is 
arguably easier to use as the device attaches to an I2C bus. In addition, the device 
characteristics are to sense light in the same spectrum as the human eye, something 
I'm not sure is true for a simple light dependent resistor solution. Further, the device 
has 16bits of sensitivity as compared to a maximum of 12 bits of sensitivity found the 
ESP32 ADC. 


This is a 3.3V device, do not attempt to power fro 5V. 
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Pin Function 
VCC 3.3V 

GND Ground 

SCL I2C Clock 
SDA I2C Data 
ADDR Address select 














The following commands can be sent by an I2C write: 









































Value Function 

0x00 Power down 

0x01 Power on 

0x07 Reset 

0x10 Mode H 

0x11 Mode 2H 

0x13 Mode L 

0x20 One time Mode H 
0x21 One time Mode 2H 
0x23 One time Mode L 





The I2C bus address of the device is 0x23. 


Here is a simple schematic illustrating the a wiring of the device. 
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BH1750FVI 





ESP32 DevKitC 











See also: 


. Rohm BH1750FVI — Data sheet 
. Wikipedia — Lux 
. YouTube: ESP32 Technical Tutorial — Ambient light levels 








Ambient light and proximity sensor 


The APDS-9930 is an ambient light and proximity sensor. This is a 3.3V device using 
I2C. 























Module pins: 

VL IR LED power 
GND Ground 

VCC 3.3V 

SCL I2C Clock 
SDA I2C Data 

INT Interrupt 
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See also: 


Data sheet 


Infrared receivers 

Infrared is a frequency range of light that is not visible to our eyes. If we look at a 
source of infrared light, we simply won't see any emissions even though they are 
actually being emitted. There are LEDs available that can generate infra-red frequency 
light and there are corresponding detectors that can measure the incoming amount of 
infrared light. Since these light sources don't distract us, we can use them for signaling 
by having an infra-red transmitter send pulses of light to an infra-red receiver. This is 
precisely how many home remote control hand-sets work for devices such as TVs and 
music systems. 


What we might want to do is to control the ESP32 remotely using an infra-red hand-set. 


There are many infra red hand-sets that we can use that can be purchase on eBay fora 
few dollars. Alternative we can use any hand-set from an old TV. 





We will also need to wire in an infra-red receiver circuit to our ESP32. 


With the transmitter (hand-set) and the receiver (electronics connected to ESP32) we 
are about ready to go. The next thing we have to consider is how to receive the data 
transmitted and how to decode it. 


One of the more popular infrared receivers is the VS1838B. 
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vs 


The pin out of this device (from left to right facing the front): 














Pin Function 

1 Data 

2 GND 

3 Vec 2.7-5.5V 














This device is able to receive at a frequency resolution of 38KHz. 


If we connect the data out to a logic analyzer and then apply an IR signal from a 
controller, we can see the incoming pulse-train. For example: 

















Obtaining the data from an IR receiver LED is supported natively by the hardware of the 
ESP32 using the RMT peripheral. It can be configured to watch for pulse trains and 
return us an array of items where each item represents the duration a signal is low and 
the duration a signal is high. From this data we obtain very accurate representations of 
the IR data. However, there are still puzzles to be solved. Most remote controls have 
multiple buttons ... power on, power off, volume up, volume down etc. Each button 
performs a distinct function and hence must be sending a distinct pattern of data to 
represent the function of that button. As such, not only do we want to detect that a 
pulse train has arrived, we also need to decode its content. It would have been nice if 
there had been one format for all remote controls, but sadly, that isn't the case. There 
are in fact quite a few protocols made by different vendors. The protocols include NEC, 
Sony SIRC, Phillips RC5, Phillips RC6 and more. 


Let us use the NEC protocol as an example. A train starts with a 9ms mark followed by 
a4.5ms space. It is safe to assume that the durations measured won't be exactly 9ms 
and 4.5ms ... so we need to accommodate tolerance to the values actually measured. 
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See also: 


SB-Projects IT Remote Control Theory 
NEC protocol 





Cameras 
It is tantalizing to think about processing real-time images in an ESP32 and to begin 
down that journey, we need to be able to source video input. 


See also: 


Github: igrr/esp32-cam-demo 





Accelerometer and Gyroscope - MPU-6050 (aka GY-521) 
The MPU-6050 is a 3.3V device. 


An accelerometer measures the force of linear acceleration. Simply put, that when an 
object is at rest (i.e. sitting peacefully on your desk), it is not being accelerated (well ... it 
actually is but we'll come back to that later). When you start to move the object, it 
undergoes acceleration. Note that this is not the same as speed. Acceleration is the 
rate of change in speed over time. When you are sitting as a passenger in your car and 
the car is moving at a constant speed and if the ride were very smooth and you closed 
your eyes, you wouldn't know you were moving. However, if the gas or brake are 
pressed, your car would change speed and you would feel acceleration while the speed 
changed. You would feel yourself pushed back in your seat when the gas is pressed 
and you would feel yourself wanting to move forward if the brake is pressed. Similarly, if 
you stand in an elevator and press a button, you feel yourself being pushed into the 
floor when it starts to rise and you would find yourself wanting to rise when it comes to a 
stop. Acceleration is a vector quantity meaning that it has a directional quality 
associated with it. In your car (assuming you are driving forward and we call the 
forward direction x) then stepping on the gas produces an acceleration in the x direction 
while stepping on the brake produces an acceleration in the -x direction. Similarly with 
the elevator, when you rise there will be an acceleration in the z direction and when you 
stop, there will be an acceleration in the -z direction. There is one more twist to the 
story ... gravity. Although you may not have thought about it, as you sit in your chair 
there is a force acting on you that wishes to accelerate you. That force is called gravity 
and the direction of the acceleration is -z. If it weren't for the chair, your body would be 
accelerated towards the floor. Even though your body isn't moving, we can consider 
this an acceleration force being applied. What this means for us is that when a device 
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such as the MPU-6050 is sitting on your desk, it will be reporting that it is accelerating 
downwards. 


The practical implication of this is very interesting. If the MPU-6050 is flat on the desk, it 
will report an acceleration in its -z direction. If we now were to tilt the device, the 
acceleration due to gravity is still present but now the direction of that force will have 
changed. The magnitude of the acceleration will remain the same but the 
measurements will now show it spread over the x, y and z axises. Working backwards, 
by examining the values of the acceleration on the x, y and z axises, we can calculate 
the orientation of the device relative to the direction of gravity (i.e. relative to up and 
down). 


Having just discussed the concept of measurement of acceleration through the notion of 
an accelerometer, we can now look at how a gyroscope comes into play. A gyroscope 
measures the change in velocity (if at all) of a device rotating around its own axis, A 
gyroscope measures changes in angular velocity. 


The MPU-6050 combines these to measure both linear acceleration and angular 
velocity. The device measures both qualities in the x, y and z axis and hence is 
considered a measurement in 6 degrees of freedom (linear acceleration in x, y and z 
and angular velocity in x, y and z). The measurement values have a 16 bit resolution. 


If our goal is to measure the orientation of the device, we may be able to see that the 
orientation can be found by examining the accelerometer values however these values 
only result in accurate answers if the device is at rest. If it is moved, then the 
acceleration due to movement can produce jittery results. If we look at the gyroscope, if 
we Start from a known orientation (eg. flat on the desk), then in principle we should also 
be able to determine the device's current orientation by adding together all the 
gyroscopic changes that have happened to it since its original known (calibrated) 
position. Unfortunately, both of these techniques introduce errors. Using the 
accelerometer, we can determine our orientation by averaging values over time to 
remove jitter. As such, it gives good values over time but poor for short term 
measurement. The gyroscope gives us good angular momentum values in the short 
term but the errors accumulate over time when we try and calculate the orientation of 
the device from its base state by successive addition of delta values. Fortunately, we 
can combine these two techniques through a variety of algorithms to give us a good 
value that is built from the combination of the two measurements. 


The MPU-6050 device connects via an I2C bus (default address is 0x68 but can be 
changed to 0x69). This is 3.3V device and hence is safe to connect to ESP32 pins 
directly. 
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The device has the following pins exposed from the breakout boards: 






































Pin Description 

VCC 3.3V 

GND Ground 

SCL I2C Clock 

SDA I2C Data 

XDA | Auxiliary I2C Data 

XCL_ | Auxiliary I2C Clock 

ADD I2C address selection, either 0x68 or 0x69. Low = 0x68, high = 0x69. 
It is not recommend to let this line float. Tie it to the desired signal. 

INT 








Asample wiring of the device to ESP32 looks as follows: 
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rY-521 MPU-6050 IMU 


ESP32 DevKitC 











After wiring, if we run an I2C scanner we will see the device: 


0 1 2 3 4 5 6 7 8 9 a becdeéi ft 


OO: ‘malian: Semtitel:: tite: Sele? cceidet: ies sk~ elem Gatiet> <ieuieis ¢lmmige'. <eme-- scence: <seaciee 
10: <= <= 25 -= n2 25 25 ne ne ne 5 we we we we =e 
20: -- <= wo ne ne ne ne ne ne ne ne nn 
30: <= -- -- ne ne ne we ne ne ne 5 we we we we =e 
AQ: -- 35 2 ne ne ne we ne ne ne 5 2 we we we =e 
50: Resciseane maa: |= Geeeieame=< Sapatomene!. ieaniteae - ecidned” Someataaet: -Sas'paes Astin” nee - “aiebillek)<clemtnee Sua Sadi- . emeeedo- stewie’: Loanaee: 
60: -- == 5 me nH He ne = 68 H= HH He ne re 
70: <= 5 25 25 25 ne ne 
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Register | Offset Name Description 
0x3B 0 ACCEL XOUT_H | AccelX High 
Ox3C 1 ACCEL XOUT_L | AccelX Low 
0x3D 2 ACCEL YOUT_H | AccelY High 
Ox3E 3 ACCEL _YOUT_L | AccelY Low 
Ox3F 4 ACCEL ZOUT_H | AccelZ High 
0x40 5 ACCEL ZOUT_L | AccelZ Low 
0x41 6 TEMP _OUT_H Temp High 
0x42 7 TEMP OUT _L Temp Low 
0x43 8 GYRO XOUT_H | GyroX High 
0x44 9 GYRO_XOUT_L_ | GyroX Low 
0x45 10 GYRO _YOUT_H | GyroY High 
0x46 11 GYRO YOUT L_ | GyroY Low 
0x47 12 GYRO ZOUT_H | GyroZ High 
0x48 13 GYRO_ZOUT_L_ | GyroZ Low 




















Note that the data values are signed 16 bits in big endian format. 


To use the I2C protocol, we send the value 0 to register PWR_MGMT_1 (O0x6b). 





Flag 


Description 





Device Reset [7] 


Reset the device 





Sleep [6] 


Put the device to sleep 





Cycle [5] 


Cycle between awake and asleep 





Temp disable [3] 


Disable the temperature sensor 








Clksel [2:0] 


Clock source of the devuce 











You will sometimes see these devices referred to as Inertial Measurement Units (IMUs). 


The value returned from the accelerometer is a raw value. The actual result we want is 
measured in gravities (g) which is about 9.81 ms*. The device has various sensitivities 
built in. To get to the real value, we need to divide by a scaling factor as show below: 
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Acceleration | Sensitivity 
Limit Factor 

2g 16384 

4g 8192 

8g 4096 

16g 2048 











Thus to get the required value from the raw value we would use the equation: 


required value = 


By default, the device is configured for a 2g acceleration limit 


raw value 
sensitivity factor 





Similarly, there is an angular velocity scaling: 




















Angular Sensitivity 
Velocity Factor 
Limit 

250°/s 131 

500°/s 65.5 
1000°/s 32.8 
2000°/s 16.4 














Figure 8. Three Axis for Measuring Tilt 
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Technical task ... send in accel values X, Y and Z. 


See also: 


Accelerometers 

YouTube — ESP32 Technical Tutorials: MPU6050 Accelerometer 
Tilt Sensing Using a Three-Axis Accelerometer 

MPU-6050 Data Sheet 

MPU6050 Register Map and Descriptions 

MPU-6050 Accelerometer + Gyro 

12Cdevlib — MPU-6050 

Filters 

InvenSense — MPU-6050 Home Page 

Gyroscopes and Accelerometers on a Chip 

Using an accelerometer for inclination sensing 

YouTube: MPU-6050 Data with a Complementary Filter 
Digi-Key: How the latest MEMS inertial modules help overcome application development challenges 



































The math of accelerometers 

Our real world is composed of three spatial dimensions. In English we might think of 
these as left/right, up/down and in/out (or forward/back). In our math, we will label these 
by the common x, y and z. If we want to think about the orientation of something, we 
can think of it as the rotation about these axis. We define the rotation around the x axis 
as "roll" designated by the symbol "®". We define the rotation around the y axis as 
"pitch" designated by the symbol "©" and finally, we define the rotation around the z axis 
as "yaw" designated by the symbol "W". So, to think about the orientation of an object, 
we can think about its roll, pitch and yaw. 





Axis /Name | Symbol 
x roll ® 








y pitch /O 

















Z yaw Y 





Now, let us merge in the notion of how we are going to measure our roll, pitch and yaw. 
Assuming no acceleration of our device (l.e it is stationary) then there will be a constant 
force on it of 1g in the z axis. So the force measured in the z axis will be 1 and x and y 
will both be 0. As we tilt the device from its horizontal orientation, that force will start to 
be distributed across multiple axis and not just the z axis. So a tilt will produce a new 
measured force value in both x and y. And here comes the magic. The measured force 
change is proportional to the roll and pitch angles. But wait, what about the yaw? Well 
... If we think about it, a rotation around the z axis does not change the tilt of what we 
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want to measure. Think of it like this, if we have a perfectly flat table top and place 
some marbles on its surface, if we tilt the table left or right, the marbles will roll. If we tilt 
it forward or back, the marbles will roll. However, if we are gentle and rotate the table 
around its central vertical axis, the marbles will not roll. They will remain in their same 
position relative to the table. 


Another way to think about this is to hold your cell phone in your hand flat while sitting 
on a chair. If you now spin around on your chair, have you changed the "tilt" of your cell 
phone? | would say no. 


What this means to us is that we can calculate the orientation of our device only by 
figuring out the roll and pitch. The yaw becomes immaterial to our story (for just now). 


By some math, we can find that: 


G 
an(e)= 


tan(|@)= Ps _s 
(6) \ Gy+G,, 


See also: 


Using an Accelerometer for Inclination Sensing 
Understanding Euler Angles 








Visualizing orientation 

It is all very good getting raw numbers representing the amount and direction of force on 
our device against different axis, but triplets of numbers isn't at all intuitive to our ways 
of thinking. Instead, what we want is a mechanism to "see" the orientation of the 
device. Since orientation is inherently a three dimensional physical consideration, what 
we want is to visualize the data as a 3D scene. There are many 3D programming 
packages on the Internet with varying degrees of sophistication and capabilities. Since 
my belief is that all user interfaces should be browser based as opposed to thick client, 

| wanted one that could run in a browser. | also wanted one that is open source. For 
this | chose "three.js". 


See also: 


three.js 


Compass - HMC5883L (aka GY-271) (aka CJ-M49) 

In the real world, a compass is a device which can be used to determine the direction of 
magnetic north. There are also electronic components that can perform the same task. 

One such component is the HMC5883L (which has been superseded by the HMC5983 
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but both are compatible with each other). Strictly speaking, the device measures the 
intensity of any magnetic field around it. Since field strength is a vector quantity (has 
both magnitude and direction), we will be measuring the field strength in the X, Y and Z 


axis. The going price for one of these on eBay is about $3. 


The calculation of a compass bearing is affected by the relative tilt of the device. What 
this means is that if the device is tilted the compass bearing result will be wrong. We 
can compensate for this if we know the amount of tilt. This can be calculated from an 
MPU-6050. 


This is a 3.3V device. 








The pin configuration for GY271 is (Left-Right as seen from chip side with connector at 




















top): 
Pin Function 
DRDY Data ready/Interrupt 
SDA I2C Data line 
SCL I2C Clock line 
GND Ground 
VCC +ve voltage — 3.3V 














The pin configuration for the CJ-M49 is (Left-Right as seen from chip side with 


connector at top): 
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Pin Function 

3V3 +ve voltage — 3.3V 
DRDY Data ready/Interrupt 
SDA I2C Data line 

SCL 12C Clock line 

GND Ground 

VCC +ve voltage — 5V 
+5V 














The module makes its data available via the I2C bus. The I2C address of the device is 
Ox1E. If we run an I2CScanner we will see the device as being present: 





0. 2 3 04 OS. 6 TB DG cas ey se. td) es -£ 


-- -- - HR F R R R R R R  H  de 


WTA oO FP WN EF CO 
> GO OO, OO. aS 





From |2C there are a set of registers that can be accessed: 















































Address Description Access 

00 Configuration register A Read / Write 
01 Configuration register B Read / Write 
02 Mode register Read / Write 
03 Data output X MSB register Read 

04 Data output X LSB register Read 

05 Data Output Z MSB register Read 

06 Data Output Z LSB register Read 

07 Data output Y MSB register Read 

08 Data output Y LSB register Read 

09 Status register Read 

10 Identification register A Read 

11 Identification register B Read 

12 Identification register C Read 
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Think of the device as having a register cursor. We can move the cursor simply by 
sending the id of the register to move to. For example, sending the device 0x03 will 
move the cursor to register 3. Subsequent reads will read from the cursor location and 
auto-increment the cursor. So moving to register 3 and reading « bytes will read the 
next 6 register values [0x03-0x08]. 


Configuration Register A (register 00) is as follows: 





Name 


Bits 


Description 





7 


Reserved. Must be 0. 





MA 


6:5 


Averaged samples per measurement: 
00 = 1 (default) 

01=2 

10=4 

11=8 





DO 


4:2 


Data output rate in measurements/second: 


000 = 0.75 

001 = 1.5 

010=3 

011 =7.5 

100 = 15 (default) 
101 =30 
110=75 

111 = Reserved 





MS 








1:0 





Measurement configuration 
e 00 -Normal (default) 
e 01 - Positive bias 
e 10-—Negative bias 
e 11 -Reserved 








Configuration Register B (register 01) is as follows: 
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Name | Bits Description 





GN TS Gain values: 

000 = 1370 

001 = 1090 (default) 
010 = 820 

011 = 660 

100 = 440 

101 = 390 

110 = 330 

111 = 230 





4:0 Reserved. Must be 0. 

















Mode Register (02) 





Name | Bits Description 





HS 7 High speed I2C control 





6:2 Reserved. Must be 0. 





MD 1:0 Operating mode: 

e 00 = Continuous 

e 01 =Single measurement (Default) 
@ 10=Idle mode 

@ 11=TIdle mode 

















The three identification registers return the ASCII values 's' (0x48), '4' (0x34) and 'c' or 
a’ (0x48), '4' (0x34) and '3' (0x33) 


To create an angle in degrees, the following formula can be used: 
angle = atan2((double)y, (double)x) * (180 / 3.14159265) + 180; // angle in degrees 


The driving logic at a high level is: 

















Function Description 

Write 0x02 Select mode register 

Write 0x00 Continuous measurement mode 
Write 0x03 Select register 3 

Read 6 bytes X, Z, Y value pairs MSB/LSB 














we combine MSB and LSB of data with: 
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data[0] << 8 | data[1]; 


Attachment of the device to ESP32 is particularly easy. As you can see it only needs 4 
wires to connect. 


Here is a schematic of how an instance of the board may be wired to ESP32. 









CJ-M49 - HMCS5883L 


ESP32 DevKitC 











When we use a compass, the result we usually want is "which way is North". On a real 
physical compass, we have a needle that points in that direction and we know our 
answer. Through a digital device, what we should expect to get back is an angle that 
the device would have to be oriented for it to point North. This assumes that there is a 
reference mark on the device from which the angle has meaning. 


When experimenting with the device, don't bring strong magnets too close to the device 
as it may become magnetized or otherwise damaged. 


See also: 


Data sheet 

Sparkfun Tutorial 

Arduino Nano + GY-271 (Digital Compass module) + OLED 
Electrodragon - HMC5883L - Three-Axis Compass 

YouTube — ESP32 Technical Tutorials: HMC5883L — Compass 

YouTube — Arduino How To: HMC5883L_ Compass Magnetometer Tutorial 
YouTube — Use the HMC5883L 3-axis sensor with an Arduino — Tutorial 
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YouTube — Let's build an Arduino electronic Compass using the HMC5883L and a Ring of LEDs - Tutorial 
Wikipedia — atan2 


Github — Arduino Library 





Tilt compensation of the compass 

When the compass module is perfectly planar, it returns a good value but if it is tilted, 
then the value is no longer true. Look at the following diagram and imagine your 
compass center in a perfect horizontal plane. At that time, there will be no roll and no 
pitch. For our purposes, the yaw of the board will be pointing vertically straight up and 
we don't care. The value of the compass will be correct. However if the board is tilted 
with roll and pitch, then the compass value is no longer accurate. However, given then 
value measured from the compass and if we have the values of roll and pitch, we can 
compensate and calculate a correct compass value. 


Z 


A 


Yaw 


Pitch 


Roll y 


Again by looking at the above image, consider an accelerometer. This will measure the 
force of gravity and gives us a reference to the orientation of the compass sensor. 
When the sensor is horizontal, the acceleration measured will be exclusively down the Z 
axis however when the sensor is titled, the acceleration will be distributed across X, Y 
and Z and by using math, we can determine the orientation of the board. As a side 
note, when the board is horizontal, the compass bearing will be the yaw value. 


We will define the following definitions: 














® — phi Roll (X) 
0 — theta Pitch (Y) 
Y — psi Yaw (Z) 
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See also: 


Implementing a Tilt-Compensated eCompass using Accelerometer and Magnetometer Sensors 
Wikipedia: Axes conventions 





Real time clocks 

When we start an ESP32, it doesn't know what the real time is. We can tell it once 
booted but even then, once we power it off, it will forget again. If the ESP32 is 
connected to the Internet, it can learn the real time by using a network time protocol. 
However, if our ESP32 is not connected to the Internet and is network isolated, by 
default, it has no mechanism to know the current time. This is what we can add a real- 
time-clock (RTC) module. A real-time clock module is a small piece of electronics that 
contains a battery and is taught the current date and time. Because it has an on-board 
battery, it can remember the time even when the ESP32 is powered off. When the 
ESP32 boots, it can be configured to ask the RTC module for the current date/time and 
use that from then on. 


There are many RTC modules available but one of the more prevalent is the DS1307. 





These can be picked up on eBay for about $1. The RTC uses battery backup when not 
powered. This is a standard CR2032 type. When inserting the battery, it is +ve down. 
When soldering on header pins, think through how you will mount the board when 
complete. It may be that you want to solder the header pins such that you can easily 
access and replace the battery once attached to your PCB or strip board. 


This device provides a real time clock capability that includes hours, minutes, seconds, 
month, day of month, day of week and year. Month calculations including leap year 
support are also accommodated. Interestingly, it also provides 56 bytes of non-volatile 
RAM. The device uses I2C for communication. 
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Note: Before plugging your board to the ESP32, realize that this is a 5V module. If you connect 5V to the ESP32 
GPIO pins bad things can happen because they are 3.3V pins. The I2C protocol uses pull-up resistors to bring the 
SDA and SCL lines high by default. If we were to look at the schematic diagram of this module we would find that 
resistors R2 and R3 are pull-up resistors. Unfortunately, we have two problems. First is that the ESP32 already 
pulls up the pins and secondly the module pulls them high to a 5V line which is too much for the ESP32. The 
solution is to physically remove these two resistors from your module before use. The resistors are clearly marked 
on the board as R2 and R3 and carry the mark 332 (3.3k). 











Since the device has battery backup, an interesting question is how long can this 
module keep time for? If we examine the data sheet, we find that it consumes 500nA 
while running on battery. If we understand that a typical CR2032 battery has a capacity 
of 200mAh then, if my math is correct, this works out to be about 45 years ... which is 
well past the life of the battery itself. 


The boards have 5 pins on one side 7 on the other. 




































































Pin | Label Description 

1 DS DS18B20 Temp. 
2 SCL I2C clock. 

3 SDA I2C data line. 

4 Vcc Vcc (SV). 

5 GND Ground. 

Pin | Label Description 

1 SQ Square wave output. 
2 DS DS18B20 Temp. 
3 SCL I2C clock. 

4 SDA I2C data line. 

5 VCC Vee (SV). 

6 GND Ground. 

7) BAT Battery voltage 








Once plugged in, we will see the RTC at I2C address 0x68: 


O° ae 2. Bs 64> 35> nO A 8 39s. a. (Bie =e wd? Se) SE 





-- = ee HR HR HR RH KK 68 HR HR OR 


HATHA OB WNEFR CO 
Oo Oo. @O'oO: Oo O--oO Oo 





Page 288 


The device has registers contained within it that are laid out as follows: 










































































Address |Bit7 |Bit6 | Bit5 Bit 4 Bit 3 Bit 2 Bit1 | Bit 0 Function | Range 
0x00 CH 10 Seconds Seconds Seconds 00-59 
0x01 0 10 Minutes Minutes Minutes 00-59 
0x02 0 0-24 | 10 hour 10 Hour | Hours Hours 1-12 
1-12 |AM/PM AM/PM 
00-23 
0x03 0 0 0 0 0 Day Day 01-07 
0x04 0 0 10 Date Date Date 01-31 
0x05 0 0 0 10 Month | Month Month 01-12 
0x06 10 Year Year Year 00-99 
0x07 OUT (0 0 SQWE 0 0 RS1 RSO Control 
0x08 - RAM 0x00 - 
Ox3f OxFF 

















The encoding of the data is known as "Binary Coded Decimal" (BCD). Each decimal 
digit is encoded as a 4 bit representation. For example, the decimal number "34" would 
be encoded as 0011 1000. The first four bits representing "3" and the last four bits 
representing "4". 


To convert a two digit decimal valued integer to a BCD representation we would use the 
expression: 

bcdValue = ((num / 10) << 4) | (num%10) 

to convert from a BCD to an integer, we would use the expression: 


num = (bcdValue >> 4) * 10 + (bcdValue & Ox0f) 


In addition to performing the service of a real time clock, this device also provides 56 
bytes of battery backed up RAM. While 56 bytes doesn't sound like much, it could be 
used to hold fourteen 32 bit integer values or perhaps an SSID/password pair. 
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DS1307 


ESP32 DevKitC 











See also: 


YouTube — ESP32 Technical Tutorials: DS1307 Real Time Clock 
Tutorial — Using DS1307 and DS3231 Real-time Clock Modules with Arduino 
Maxim integrated datasheet 











Servos 

A servo is a physical movement device similar to an electric motor. Typically, a servo 
has a rotation shaft that can rotate from 0 degrees to 180 degrees as a function of the 
incoming signal applied to it. If one sets the signal to a specific value, the shaft will 
rotate to a specific position as a function of that signal. The actual minimum and 
maximum angles are specified by the manufacturer of any particular servo model. 


The signal expected by a servo is encoded as Pulse Width Modulation (PWM). One 
should always consult the manufacturers data sheet to find the specific values. 
However, in general, the story works as follows. 


Typically, the period of the PWM is 20 milliseconds. If we think this through, we will 
realize that 20ms is 50Hz as there are 50 instances of 20ms periods in 1 seconds 
(1000ms). At the start of the period, the duration that the signal is high determines the 
rotation of the shaft. For example, it may be defined that there is a minimum value of 1 
millisecond and a maximum value of 2 milliseconds. This means that if the signal is 
high for 1 millisecond, the shaft rotates to its minimum value. If the signal is high for 2 
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milliseconds, the shaft rotates to its maximum value. For high durations between 1 and 
2 milliseconds, the shaft rotates proportionally to that duration. 


Here is a diagram (not drawn to scale) to illustrate the principle: 


20 msecs 


—_—_—_—_—_$§S _${=_<a_a_ecCS i 


1.0 msecs 


| <j #4 


2.0 msecs 


it LEe 
| OUfL ed 


Again, it is important to read the data sheet to find the correct values for minimum and 
maximum duty cycle widths. 


We also need to remember that the voltage output from a ESP32 GPIO pin is 3.3v. 
Most of the servos require a signal at the 5v level. This means that we can't directly 
drive a servo's data signal input from a ESP32 pin. We will need to employ a logic level 
shifter to shift the output PWM signal from 3.3V up to 5V. 


If we use the ESP-IDF drivers and we imagine that the minimum duty cycle is 1ms and 
the max is 2ms with a period of 20ms, then we see that the range of duty cycle is 1ms 
which is 1/20th of the period. This then gives us the granularity of adjustment for the 
servos by looking at the different bit sizes available for the PWM timers: 
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Bit Size Granularity (1ms spread) | Low (1ms) High (2ms) 
10 51 51.2 102.4 

11 102 102.4 204.8 

12 204 204.8 409.6 

13 408 409.6 819.2 

14 819 819.2 1638.4 

15 1638 1638.4 3276.8 

See also: 


Pulse Width Modulation — PWM 


The Mini/Micro SG90 


The mini/micro SG90 servos can be found on eBay for under $2 each. These servos 
weight only 9g. They have a stall torque of 1.8kg-cm, operate at 5v, have a speed of 
about 0.3 seconds for 180° and have discrete step instances of 10us. The stalled 
current draw on one of these servos is reported to be 600mA. 


























Color Function 

Red Vcc 

Brown Ground 

Orange PWM 
See also: 


¢ Mini/Micro SG90 — Data sheet 


Audio 


PCM5102 - 12S DAC 


This device takes as input an I2S signal and produces an analog audio output. 
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Pin Function 
VCC 
3.3V 
GND 
FLT Filter select 
DMP De-emphasis 
SCK System clock input 
BCK Audio data bit clock input 
DIN Audio data in 
LCK Audio data word clock input 
FMT Audio format selection 
XMT Mute control 
See also: 
12S Bus 
Data sheet 


Graphic Equalizer 
An integrated circuit called the MSGEQ7 is a graphic equalizer. It can operate at 3.3V 


or 5V. 


If we provide it an audio input signal, it will analyze the signal into 7 discrete frequency 
bands of 63Hz, 160Hz, 400Hz, 1KHz, 2.5KHz, 6.25KHz and 16KHz. 


The integrated circuit is supplied in an 8 pin configuration with: 









































Pin Function |Description 

1 VDDA 3.3-5V power supply 

2 VSSA Negative 

3 OUT Multiplexed DC Output. This is an analog output value. 

4 STROBE  |Channel selection 

5 IN Audio input 

6 GND_REF 

7 RESET Reset. A high resets the multiplexor, low enables the strobe. 
8 CKIN Clock. This is passive component clock circuit. 
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VDDA CKIN 











VSSA RESET 
OUT GND_REF 
STROBE _ IN 
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Yellow reset - 16 
Blue Strobe - 17 
Green Out 


[3.3V] [GND] [OUT - GREEN — GPIO 36] [STROBE BLUE — GPIO 17] [ RESET — 
YELLOW - GPIO 16] 


The high level of operation is that we apply our audio signal in "rn" pin. Normally, the 
RESET pin is low. When it goes high and then low again, the decoding of the signal is 
latched. Now we can read data from the "out" pin which is an analog value. The 
STROBE pin is initially high. When it goes low, we can read the value of our. When it 
goes high and then low again, we will have stepped onto the next frequency. 




















A high level algorithm would be: 


pinMode (RESET, OUTPUT) ; 
pinMode (STROBE, OUTPUT) ; 
pinMode (OUT, ANALOG) ; 




















digitalWrite (RESET, LOW); 
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digitalWrite (STROBE, HIGH); 








digitalWrite (RESE 


delay(1); 
digitalWrite (RES 











T, HIGH); 





ET, LOW); 





delay(1); 


digitalWrite (STRO 


delay(1); 


BE, LOW); 


v63hz = analogRead (OUT) ; 


digitalWrite (STRO 


delay(1); 


digitalWrite (STRO 


delay(1); 


BE, HIGH); 


BE, LOW); 


vl60hz = analogRead (OUT) ; 


digitalWrite(STRO 


delay(1); 


digitalWrite (STRO 


delay(1); 


BE, HIGH); 


BE, LOW); 


v400hz = analogRead (OUT) ; 


digitalWrite (STRO 


delay(1); 


digitalWrite (STRO 


delay(1); 


BE, HIGH); 


BE, LOW); 


vl000hz = analogRead (OUT) ; 


digitalWrite (STRO 


delay(1); 


digitalWrite (STRO 


delay(1); 


BE, HIGH); 


BE, LOW); 


v2500hz = analogRead (OUT) ; 


digitalWrite(STRO 


delay(1); 


digitalWrite(STRO 


delay(1); 


BE, HIGH); 


BE, LOW); 


v6250hz = analogRead (OUT) ; 


digitalWrite (STRO 


delay(1); 








digitalWrite (STRO 





delay(1); 


vl6000hz = analog 


BE, HIGH); 





BE, LOW); 





Read (OUT) ; 


For an easy wiring solution, breakout modules exist. These provide an MSGEQ/7, pin 
outs, passive components and signal input sockets on a single board ready to be wired 


In. 
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The pins exposed are: 
* vcc — Power 


* cnpd—Ground 








* RESET — Reset pin (input) 








* STROBE — Strobe Pin (input) 








* out —Analog output 


See also: 


Datasheet 
MSGEQ/7-Based DIY Audio Spectrum Analyzer: Construction 








External networking 

It may seem strange to include additional networking hardware interfacing given that the 
ESP2z2 is a first class WiFi and Bluetooth device however there are times when we want 
to performing networking which doesn't fit either of those categories. While WiFi and 
Bluetooth are great, you may have to interact remotely with devices which don't support 
those protocols. A classic example are the cheap nRF24 modules from Nordic. These 
devices are reported to easily be able to transmit and receive over 300 feet and hence 
become ideal components for longer distance communications. 


The nRF24 

The nRF24L01 is an extremely cheap communication device. It allows one to transmit 
and receive data over large distances (hundreds of feet). It transmits and receives 
packets between similar devices. Do not confuse it with WiFi or Bluetooth. You can 
transmit from one nRF24 to another nRF24 but not to anything else. There are a 
number of reasons to consider this device for projects over others. First is the very low 
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cost. An instance of the device can be picked up for less than a dollar. Second is the 
peer-to-peer nature of the devices. There does not need to be a master/slave 
relationship in the story. In fact, two or more devices can exchange packets with each 


other without any of them acting as controllers. There are occasions where this is 
exactly what is needed. 





The device operates on 3.3V and uses SPI as a protocol. The pin-out on the nRF24L01 


























IS: 

Pin Description 

Vcc 3.3V 

GND Ground 

MISO SPI Master In/Slave Out. 

MOSI SPI Master Out/Slave In. 

SCK SPI System clock. 

CSN SPI Chip Select — Enable the device (active low). Normally this will be wired to ground. 

CE RX or TX mode. The Data sheet calls this Chip Enable which seems an awfully strange name for a 
communication mode selector. CE=1 for transmit while CE=0 for receive. 

IRQ Maskable interrupt. 











Seen from above, the pins are: 














GND VCC 
CE CSN 
SCK MOSI 
MISO |IRQ 
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Some of the key specifications of this component include up to 2Mbps transmission rate 
and low power consumption. It operates in the 2.4GHz wireless band. 


The device operates in a variety of different modes ... here is the state transition 
diagram for them which taken from the Datasheet: 
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Legend: 


Undefined 


C) Recommended operating mode 
C) Possible operating mode 


. 
/ ‘ 
‘ 
H | Transition state 
/ 
/ 


“”™ Recommended path between operating modes 
Possible path between operating modes 


ne i PWR_UP=0 
ce=1 Pin signal condition - 
PWR_ON=1 Bit state condition 
TX FIFO empty System information 
PRIM_RX = 0 
TX FIFO empty 


CE=1 








7 . 
7 N 
A 
RX Settling | PRIM_RX=1 
{ "430us | CE=1 
\ / TX FIFO not empty 
‘. 4 


TX FIFO not empty 
CE=1 


¢ \ 
! 
RX Mode at TX FIFO empty 
cEs1 
PWR_UP=0 
PWR_UP=0 


CE=1 
TX FIFO not empty 


The first mode is "Power Down". This is the lowest power mode while still maintaining 
state/configuration. 


The second mode is called "Standby". Again in this mode it is consuming low amounts 
of power but not as much as "Power Down". The difference between this mode and 
"Power Down" is how quickly it can begin transmitting and receiving. 


The third mode is called "RX". In this state the device is a receiver. 


The final mode is called "TX" and is entered when the device is transmitting data. 
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The modes are entered through: 




















Power Up |CE |PRIM RX |TX FIFO 
Power Down 0 - - 
Standby 1 0 - 
RX 1 1 1 
TX 1 1 0 >0 




















There are two data transmission rates ... 1MBps and 2MBps. It is vital that both the 
transmitter and receiver devices use the same data rate. 


The communications protocol used by the nRF24 devices is called "Enhanced 
ShockBurst". It has a dynamic payload length of between 1 and 32 bytes. What this 
means is that a single transmission can be up to a maximum of 32 bytes in total. If we 
need to transmit additional data, we would send a stream of packets one after the other. 
Automatic transaction handling is also provided. We should think of a transaction as the 
request from the transmitter to send a packet and have the receiver pick it up. It is 
possible that there may be errors in the transmission. The transaction solution is to hold 
the transmitted data until there is a positive acknowledgment that the receiver has 
actually received it. If that doesn't happen, the transmitter can re-transmit the packet. 


To set the size of the payload of a packet, we have two choices available to us ... these 
are static and dynamic sizes. For the static size, the receiver specifies the size of the 
payload and the sender must send that size before a transmission is complete. For 
dynamic payload, the transmitter can send a variable number of bytes before that 
packet is acknowledged as receiver by the receiver. 


Each device has an assignable address. When data is transmitted from one device to 
another, the transmitter specifies the address of the receiver. An address can be 
between 3 and 5 bytes in length. 


Devices communicate on a "channel". Think of this as a specific radio frequency 
bandwidth chunk. In order for a transmitter and receiver to talk to each other, they must 
both agree on the channel to be used. Achannel is 7 bits in length (0 to 127). The 
default is channel 2. 


The nRF24 has a variety of communication speeds including 1Mbps and 2Mbps. 


A Cyclic Redundancy Check (CRC) can be applied to the payload to assist in detection 
of transmission errors. The CRC size can be set to be 8 bits or 16 bits. 


The transmission power can be adjusted. The more transmission power you request 
the more overall power will be consumed and if you are running from batteries, this may 
be a consideration. There are four settings: 
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Output power Current consumption 
0dBm 11.3mA 

-6dbM 9.0mA 

-12dBm 7.5mA 

-18dBm 7.0mA 














A handy little addition to a nRF24 module is a YL-105. This is a connector board that 
hosts a nRF24 but also exposes the pins on the top in a line. One of the issues (at least 
to me) when working with nRF 24s is that they have the pins pointing downwards and | 
have to do mental mirror imaging to get things right (and don't always). 





The pins are: 
° CE 
° CSN 
° SCK 
¢ MOSI 
* MISO 
« IRQ 
and two further pins for: 
* VCC 
* GND 


When pairing a couple of nRF24s, | find it useful to create a spreadsheet with two 
columns; one for each of the devices. We can then validate that the settings necessary 
to be paired on both are correct. 
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Attribute Device A Device B 

Addr1 TX: RX: 

Addr2 RX: TX: 

Address Width 

RF_CH 

Data Rate 

CRC Length 

Notes: 
¢ The air data rate must be the same on all participants. 
¢ The RF channel frequency must be the same for all participants. 

See also: 


Nordic Semi — Home Page 

Data sheet 

SPI — Serial Peripheral Interface 

Tutorial: Ultra Low Cost 2.4 GHz Wireless Transceiver with the FRDM Board 
Julian llett #1 

NREF24L01 - How To 

Adding a nRF24L01 to a breadboard or stripboard 

Tutorial 0: Everything You Need to Know about the nRF24L01 and MiRF-v2 
YouTube: Getting started with the nRF24L01 




















Using the Arduino APIs 





An Arduino library for the nRF24 is available called RF24. This library is highly active 
and well documented. It appears to be a fork of the RF24 library originally created by 
Manicbug. It has a detailed set of documentation including descriptions of all the class 


APIs. 


A typical flow would be: 


RF24 radio(CE PIN, CSN PIN); 


radio 


radio. 
radio. 


radio 


// To 


radio. 





-begin(); 


setPALevel (RF24 PA LOW); 
openWritingPipe (addressTX) ; 


.openReadingPipe (1,addressRX) ; 


be a receiver ... 
startListening(); 


To stop being a receiver, call: 


radio. 


stopListening(); 
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Since there are only two modes, a receiver and a transmitter, when one stops being a 
receiver, one immediately becomes a transmitter. 


To determine if there is data available to receive, call: 


radio.available() 


To read data, we can call: 


radio.read(&buffer, length) ; 


To write, we can call: 


radio.write(&buffer, length); 
The library comes with some samples. 


* GettingStarted — Two devices. One can act as the transmitter and one as the 
receiver. They can be flipped around through user input from the serial port. 


Before the library can be used, an instance of it must be constructed. The constructor 
looks as follows: 


RF24(cePin, csPin) 


The Arduino pins for ce and cs need not be fixed and hence we must instruct the library 
as to which pins we actually used. Take care that when an instance is created you 
specify the pins in the correct order as there is no guard against that. 


Before any other functions can be called, we must call begin (). This perform the 
initialization of the device plus sets defaults for many of the operational parameters. 


Every device has an address associated with it. This allows a transmission from one 
source device to be addressed to a specific destination device. When a transmission 
occurs, devices other than the one with the matching address will ignore the 
transmission. The device requires the size of the address to be supplied and fixed. The 
allowable address sizes are 3, 4 or 5 bytes. The default is 5 bytes. The size of the 
address can be changed with the setAddresswidth() method however you are unlikely 
going to want to change the default value. You must remember to supply the full data 
for the address. For example, don't set an address of "123" when the address size is 5 
bytes as your device address will become "123<?><?>" and you will likely waste time 
trying to find out why no data is coming to you. 


At this point, we must consider what we are going to do with the device from here on. 
The device has two modes of operation. It can transmit data or it can receive data but it 
can't do both simultaneously. 


Let us look first at being a transmitter. First we create a "pipe" over which the data will 
flow. We supply the address of the destination. 
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openWritingPipe (const unit8 t *address) 


For example: 
unit8 t address = "1Node"; 


openWritingPipe (address) ; 


We are now ready to actually transmit some data. 


bool write(const void *data, uint8 t length); 


This method will transmit the data pointed to by the data pointer for the number of bytes 
supplied in length. There is a maximum size as specified by the get PayloadSize () 
method and you should not exceed that. The method will block until the data has been 
transmitted or the transmission request has timed out. The time out is short, about 
70ms so you won't block for long. Upon return from the method call, we can determine 
whether the transmission was successful or if it failed. Areturn value of true means we 
succeeded while false means as failure. 


The device has a maximum transmission size that is 32 bytes. You can not transmit 
packets larger than this. The default maximum transmission set in the library is 32 
bytes which is the maximum that the device will permit. You can change this with the 
setPayloadSize() method but it is unlikely you will need that function. Simply 
remember that we can not ever send a payload size greater than 32 bytes. 


The other mode of the device is that of a receiver where we actually listen for incoming 
data. As mentioned, the device can either be in transmit mode or receive mode. 


To receive incoming data, we need to supply the address of the device from which we 
are expecting incoming data to arrive. We do this using the openReadingPipe() method. 
openReadingPipe(uint8 t number, const uint8 t *address) 

Once we have specified the address of the transmitting device we will receive data 
from, we can start actively listening using the startListening() method. Should we 
wish to end listening mode, we can call the stopListening() method which will return 
us to transmission mode. 


Once we have entered listening mode, we can ask the library if there is data available 
for us to read. The method for this is available(). If there is data available, the return 
value is true and false otherwise. 

To actually read the data that was received, we can use the method called read(). 


read(void *buf, uint8 t len) 


This method supplies a buffer into which the received data will be stored. The length of 
the buffer is also supplied. 


A debug file called printDetails() is provided which logs the state of the nRF24 to the 
stdout. In order to use this one must: 
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¢ Include <printf£.h> 
: Call printf begin () 


When the printDetails() function is then called, a status of the nRF24 is written to the 
Serial port. This can be a powerful tool for debugging problems. Here is an example of 
the output: 























STATUS = 0x0e RX _DR=0 TX _DS=0 MAX RT=0 RX_P_NO=7 TX _FULL=0 
RX ADDR PO-1 = 0x0045444f4e 0x0045444f4e 

RX ADDR _P2-5 = Oxc3 Oxc4 Oxc5S Oxc6é 

TX ADDR = 0x0045444f4e 

RX PW P0-6 = 0x20 0x20 0x00 0x00 0x00 0x00 
EN AA = 0x3f 

EN_RXADDR = 0x02 

RF_CH = 0x4c 

RF_SETUP = 0x03 

CONFIG = 0x0f 

DYNPD/FEATURE= 0x00 0x00 

Data Rate = 1MBPS 

odel = nRF24L01+ 

CRC Length = 16 bits 

PA Power = PA_LOW 


The complete API can be found documented at the project's web site but here is a quick 
summary: 
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Method 


Notes 





bool begin () 





void startListening() 





void stopListening() 





bool available () 


Returns true if there is data available to be read. 





void read ( 
void *buf, 


uint8 t len) 





bool write ( 
const void *buf, 
uint8 t len) 


One must call stopListening() before writing. 





void openWritingPipe ( 
const uint8 t *address) 





void openReadingPipe ( 
uint8 t number, 
const uint8 t *address) 





void setAddressWidth ( 
uint8 t addressWidth) 





void setRetries ( 
uint8 t delay, 





uint8 t count) 





void setChannel (uint8 t channel) 





uint8 t getChannel () 





void setPayloadSize(uint8 t size) 





uint8 t getPayloadSize() 





uint8 t getDynamicPayloadSize() 





void enableAckPayload () 





void enableDynamicPayloads () 








void enableDynamicAck () 





bool isPVariant () 





void setAutoAck (bool enable) 





void setAutoAck(uint8 t pipe, 
bool enable) 





void setPALevel (uint8 t level) 





uint8 t getPALevel (void) 











bool setDataRate ( 
rf24 datarate_e speed) 


Values of the enumeration are: 
¢ RF24 1MBPS 
e RF24 2MBPS 
¢  RF24 250KBPS 





rf24 datarate_e getDataRate() 








Values of the enumeration are: 
¢ RF24 1MBPS 
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*  RF24 2MBPS 
° RF24 250KBPS 





void setCRCLength ( 
rf24 crclength_e length) 


Values of the enumeration are: 
¢ RF24 CRC_DISABLED 
¢ RF24 CRC 8 
* RF24 CRC _16 








rf24 crclength_e getCRCLength () 


Values of the enumeration are: 
e RF24 CRC_DISABLED 
« RF24 CRC 8 
« RF24 CRC_16 





void disableCRC () 





void maskIRQ ( 
bool txOk, 
bool txFail, 
bool rxReady) 





void printDetails() 











Here is an example breadboard layout: 


AFPQUINO 





fritzing 
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Arduino pin nRF24 Function Color code 
Pin 13 SPI CLK 

Pin 12 MISO 

Pin 11 MOSI 

Pin 8 CSN 

Pin 7 CE 

3v3 3v3 

GND GND 














Here is a sample to have an Arduino read data from the device: 


#include <SPI.h> 
#include <printf.h> 
#include "RF24.h" 


RF24 radio(7,8); 


byte addressrx[5] = {0Oxll, 0x22, 0x33, 0x44, 0x55}; 


void setup() { 
Serial.begin (115200) 


radio.begin(); 


, 


radio.setPALevel (RF24 PA HIGH); 
radio.setChannel (0x4c); 
radio.setCRCLength(RF24 CRC 8); 
radio.setDataRate(RF24 2MBPS) ; 
radio.setAddressWidth (5); 
radio.setRetries (5,15); 


radio.enableDynamicPayloads () ; 


radio.openReadingPipe (1,addressrx) ; 


radio.startListening 

printf begin(); 

radio.printDetails() 
} // End of setup 





void loop () 
{ 


if (radio.available ( 


()F 


, 


{ 


Serial.print ("Size of payload is "); 


Serial.printlin(radio.getDynamicPayloadSize()); 


while (radio.available()) { 


char buffer[33 
uint8 t length 
radio.read (buf 
buffer[length] 


, 


= radio.getDynamicPayloadSize(); 





fer, length); 
= 0; 


Serial.print ("Received: "); 


Serial.printin 
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(buffer); 


} 
} // End of Loop 





See also: 


Github project — tmrh20.github.io 


Project Blog 
Forum thread 


Programming using Eclipse 

Eclipse is a popular open source framework primarily used for hosting application 
development tools. Although primarily geared for building Java applications, it also has 
first class C and C++ support. At the time of writing, the currently available release of 
Eclipse is called "Neon". 


Let us now look at how we can setup an Eclipse environment for an Esp-1pF template 
application. 





1. Start with ESP-IDF installed and the environment variable tpF_patu defined. 


2. Make a directory called workspace and change into it. 


S$ mkdir workspace 
S$ cd workspace 


3. Clone the template app into the workspace folder 


git clone https://github.com/espressif/esp-idf-template.git myapp 


4. Run the make menuconfig command to create the sdkconfig file. 


S cd myapp 
S make menuconfig 
S Cd a 


5. Launch Eclipse. 


6. When prompted for the workspace, provide the directory you just created 
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Select a directory as workspace 


Eclipse uses the workspace directory to store its preferences and development artifacts. 
Workspace: /home/kolban/esp32/esptest/apps/workspace v | Browse... 


{_]) Use this as the default and do not ask again 


> Recent Workspaces 


Cancel OK 











7. Switch to the C/C++ Perspective 





Open Perspective 


Lickel (qr 

4% Debug 

fa Git 

&* JavaScript (default) 

© Planning 

& Remote System Explorer 
[® Resource 


&° Team Synchronizing 
@ web 
xX XML 











8. Create a new empty C project with the same name as your project (eg. myapp). 











[s Project Explorer % | m “7 SP fal | 
New , Project... 
Import... C Project 
Export... C++ Project 
Refresh FS Static Web Project 
Example... 
Other... Ctrl+N 
| 
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C Project 


C Project <> 
& Directory with specified name already exists. 


Project name: myapp Go 


@ Use default location 





Browse.. 


hoose file syste 


Project type: Toolchains: 
Vv @ Executable — Other Toolchain — 
® Empty Project Linux GCC 


® Hello World ANSI C Project 
> @ Shared Library 
> G Static Library 
Vv @ Makefile project 


Empty Project ; 


@ Show project types and toolchains only if they are supported on the platform 


@ <Bac Next > cancel _ (iirinishi) 











9. Open up the project properties and visit C/C++ Build. Change the settings to 


look as follows: 
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Properties for myapp 








q| C/C++ Build Cie eae 
> Resource 
Builders Configuration: Default [Active] + | |Manage Configurations... 
Y C/C++ Build 
Build Variables 
Environment ElBuilder Settings | @Behavior Refresh Policy 
Logging Builder 
Settings 4 . 
Builder type: 


Tool Chain Editor 
> C/C++ General 
Git Build command: |make | Variables... 
Project Facets 
Project References 
Run/Debug Settings 
Server Build location 


Task Repository Build directory: |${workspace_loc:/myapp}/| 


Task Tags 
Validation Workspace... | | File system...| | Variables... 


WikiText 


[] Use default build command 


Makefile generation 


M j 
ene ake 


v 


7 


Restore Defaults Apply 


® cancel | (NRE 











10.In the global properties set c/c++ > Build > Environment add two variables 
called Ipr_PaTH and PatH as shown: 
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type Filter text @ Environment a 


> General 
v C/C++ Environment variables to set Add... 





Appearance Variable Value 
Y Build IDF_PATH | /home/kolban/esp32/esptest/esp-idf 
Build Targets PATH | S{PATH}:/opt/xtensa-esp32-elf/bin Edit 
Build Variables 
Console 
Environment Undefine 
Logging 
> Makefile Editor 
Settings 
Code Analysis 
> Code Style 
> Debug 
> Editor 
File Types 


@ Append variables to native environment 


_) Replace native environment with specified one 
Indexer 


Language Mappin ~ 


» 


Restore Defaults Apply 











The rtpF_patH variable points to the root of your ESP-IDF installation and the path patu 
is augmented to point to the Xtensa ESP32 tool chain. 


11. Open the properties dialog called c/c++ General > Paths and Symbols and add 
the following: 
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Properties for myapp 








@ Paths and Symbols oy 
> Resource 
Builders Configuration: | Debug [Active] > | |Manage Configurations... 
> C/C++ Build 
Vv C/C++ General 
> Code Analysis (8 Includes | # Symbols A Libraries @ LibraryPaths | GS SourceLocation & Output Location |» 
a Languages Include directories Add... 
ile Types 
¥P Assembly (©. ${IDF_PATH}/components/esp32/include : 
Formatter Edit... 
ate? GNUC (5. ${IDF_PATH}/components/newlib/include 
* mal sect (© ${IDF_PATH}/components/freertos/include Delete 
anguage Mappings B ees 
IDF_PATH}/components/nvs_Flash/include 
Paths and Symbols S{IDF_ M = iiikien di Export 


(2 ${IDF_PATH}/components/driver/include 
(5 ${IDF_PATH}/components/log/include 
& /myapp/build/include 


Preprocessor Includ: 

Git 

Project Facets 

Project References 

Run/Debug Settings 
> Task Repository 

Task Tags 
> Validation 

WikiText @ "Preprocessor Include Paths, Macros etc." property page may define additional entries 


@ Show builtin values 


Move Up 


Move Down 


Import Settings... |“ Export Settings... 





Restore Defaults Apply 











Also ... components/tcpip_adapter/include 
Also ... components/Iwip/include/Iwip 
Also ... components/spi_flash/include 


What this does is tell the Eclipse tooling where to go look for include directories to 
satisfy the inclusions from the C source files. 


12. Add a build target for the Makefile called a11: 
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[& Project Explorer % | as Sl fal | 
v SS >myapp [myann macterl | | 
> Includes New y 
> @ build Sida 
> Gy main Open in New Window 
[ LICENSE Show in Local Terminal » 
[% Makefile Copy Ctrl+c 
README.s! 
— > sdkconfig Delete Delete 
— sdkconfig.¢ ove From Context 
Source , 
Rename... F2 
Import... 
Export... 
Build Project 
Clean Project 
Refresh FS 
Close Project 
Close Unrelated Projects 
Build Configurations | a 
Build Targets , Create... 
Index » Build... Shift+F9 
Validate Rebuild Last Target F9 
Show in Remote Systems view ) 
Din Ac . 














Create Build Target 
Targetname: all fmm 


Build Target 
(@ Same as the target name 


Build target: 

Build Command 

@ Use builder settings 
Build command: 

Build Settings 

@ Stop on first build error 
@ Run all project builders 


Cancel 
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13.Run Build Targets > all: 








[& Project Explorer as | 
Y fg > Myapp [myapp master] 
¥ © Build Targets 
all 


Edit... 
> ig Includes 
> @ build Copy 
> Gy main Paste 
3j LICENSE Delete es 
[% Makefile Build Target Fe 
—j README.rst Rebuild Last Target 


[ > sdkconfig 








=| sdkconfia.old 





This causes the Makefile for the project to be run and the compilation proceeds. 


14.Examine the console. 





[?) Problems | Tasks © Console & |] Properties =g Progress 


warcLeur yo Pee, WY wy Cope), Cop es cy Upp sy wer nop 
CC tcpip_adapter_lwip.o 

AR libtcpip_adapter.a 

make[1]: Leaving directory '/home/kolban/esp32/esptest/apps/workspa 
make[1]: Entering directory '/home/kolban/esp32/esptest/apps/worksp 
CC main.o 

AR libmain.a 

make[1]: Leaving directory '/home/kolban/esp32/esptest/apps/workspa 
LD app-template.elf 

esptool.py v2.0-dev 

To flash all build output, run ‘make flash" or: 

python /home/kolban/esp32/esptest/esp-idf/components/esptool_py/esp 


23:53:38 Build Finished (took 35s.36ms) 











We should see a clean build. 


And with that you have build a binary. Now if you edit the source files and re-build the 
Makefile target called "a11", only the changed files will be shown. Should there be a 
compilation error, we will see them all highlighted in the console, in the code and in the 
project explorer. Double clicking in the console will take us to the associated source file 
and line within that source file. 
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[& Project Explorer % AS eS) [ml {e] main.c 8 


/ wanewuue Uliversypiu.t 














¥ (9 > myapp [myapp master] 
¥ © Build Targets 9>esp_err_t event_handler(void *ctx, system_event_t *event) 


le { 


@ clean 12 } 


13 


> i Includes 14> int app_main(void) 
: 15 { 
» @ build ~y 16 nvs_flash_init(); i“ 


Y gy > main 17 system_init(); 
‘ 18 fat ita thetlo world" i = “hello world"; 
¥ di > main.c 19 tcpip adapter init(); 
ul driver/gpio.h 20 ESP_ERROR_CHECK( esp_event_loop_init(event_handler, NULL) ); 
4 tl h 21 wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT(); 
€sp_event_loop. 22 ESP_ERROR CHECK( esp wifi_init(&cfg) ); 
Ul esp_event.h 23 ESP_ERROR_CHECK( esp_wifi_set_storage(WIFI_STORAGE_RAM) ); 
i. ~ h 24 ESP_ERROR_CHECK( esp_wifi_set_mode(WIFI_MODE_STA) ); 
=I esp_system. 25 wifi_config t sta_config = { 
esp _wifi.h 26 «sta = { 
z Pl 27 -ssid = “access point_name", 
ul Freertos/FreeRTOS.h 28 -password = "password", 
Ui nvs_flash.h 29 _  +bssid_set = 0 


p? app_main(void) : int 
© event_handler(void*, system_event_t*): esp_| [#) problems ] Tasks & Console 53 i Properties =y Progress 


Lig col nent.mk CDT Build Console [myapp] 

fq LICENS' make[1]: Leaving directory '/home/kolban/esp32/esptest/apps/workspace/myapp/ 
lt Makefile make[1]: Entering directory '/home/kolban/esp32/esptest/apps/workspace/myapp 
README. rst CC main.o 

— > sdkconfig /home/kolban/esp32/esptest/apps/workspace/myapp/main/./main.c: In function * 


/home/kolban/esp32/esptest/apps/workspace/myapp/main/./main.c:18:13: error: 
int i = “hello world"; 

/home/kolban/esp32/esptest/apps/femeneee/ myapp/main/ ./main.c:18:9: warning: 
int i = "hello world"; 


a 


{ sdkconfig.old 


ccl: all warnings being treated as errors 
/home/kolban/esp32/esptest/esp-idf/make/component_c -mk:110: recipe for 
make[1]: *** [main.o] Error 1 

make[1]: Leaving directory '/home/kolban/esp32/esptest/apps/workspace/myapp/ 
/home/kolban/esp32/esptest/esp-idf/make/project.mk:251: recipe for target 'm 
make: *** [main-build] Error 2 


00:01:16 Build Finished (took 1s.76ms) 











You can also add other build targets such as: 


* flash —To perform a flash of your application against your ESP32. 





* clean -— To Clean the current build. 
Short cuts are also available for some of the more common tasks. For example: 
¢ 9 — Will re-execute the last build you performed. 


* The menu bar entry will perform a"make all". 


Here are some additional Eclipse tips | recommend: 
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¢ By default, any changed files are not saved before building. | often find | make a 
change and rebuild and test only to find no difference in execution only to realize 
that what | built did not include my changes because | hadn't saved the source 
file. We can automate the saving of source files before a build by setting the 
preferences entry in General > Workspace and checking "Save automatically 
before build": 


Preferences 








(yetekallesmecnt: | Workspace 
Y General See ‘Startup and Shutdown' for workspace startup and sh 
> Appearance 
Compare/Patch @ Build automatically 
Content Types : ; ; 
> Editors Refresh using native hooks or polling 
Error Reporti @ Refresh on access 
Globalization @ Save automatically before build 
—_ _) Always close unrelated projects without prompt 
> Network Connecti 


Notifications 
Perspectives Workspace save interval (in minutes): |5 


Search Workspace name (shown in window title): |workspace 
Security 


Startup and Shutc Workspace path: /home/kolban/esp32/esptest/apps/wo 


UI Respo' enes: - ane ; 
Use age Serv Show workspace path in window title 
Ww owser 


> workspace Open referenced projects when a project is opened 


v 


od 


> C/C++ -) Always © Never @ Prompt 











¢ Install the Eclipse Path Tools package. 


¢ The primary editor font and font size can be changed at the preferences setting 
located at General > Appearance > Colors and Fonts | C/C++ > Editor > 
C/C++ Editor Text Font and then clicking "Edit...": 
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Preferences 


@ Colors and Fonts - 





¥ General Colors and Fonts (? = any character, * = any string): 


v Appearance 2 
@ 


Colors and Font: te %) 
> @a Basic b Edit... 


Label Decoratio 








¥ Ga C/C++ 
a v : i Use System Font 
Content Types ( Editor 
> Editors C/C++ Editor Text Font (overrides default: Te Reset 
Error Reporting Aa C/C++ Build Console Text Font (set to default: 
Globalization > @ Debug 
eel 
sa nani : Go to Default 
> Network Connecti > @ JavaScript 
Notifications > (@ Remote System Explorer : Expand All 
Perspectives ; 
Search Description: 
> Security The C/C++ editor text font is used by C/C++ editors. 





My personal preference is "Liberation Mono" at 11pt. 


Installing the Eclipse Serial terminal 
Note: My retests of this crash Eclipse. | have since switched to opening a shell within 
Eclipse and running minicom within the shell. 


Although there are many excellent serial terminals available as stand-alone Windows 
applications, an alternative is the Eclipse Terminal which also has serial support. This 
allows a serial terminal to appear as a view within the Eclipse IDE. It does not come 
installed by default but the steps to add are not complex. 


First start Eclipse (| use the Luna release). 
Go to Help > Install new software... 
Select the eclipse download repository. 


Select General Purpose Tools > TM Terminal via Remote API Connector Extensions 
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[ 
E 


7 = 


Available Software 





Check the items that you wish to install. 








bal 
Work with: Mars - http://download.eclipse.org/releases/mars v 
Find more software by working with the “Available Software Sites” preferences. 


type filter text 
















































































| Name Version | 
4 |) 0 Mobile and Device Development 
&& C/C++ GDB Hardware Debugging 8.7.0.201506070905 
{C/C++ Remote (over TCF/TE) Run/Debug Launcher 1.3.1.201506040227 
~ |S2 Hybrid Mobile Application Development Tools 0.3.0.201506011443 =| 
' |4 Remote System Explorer User Actions 3.7.0.201505221634 
~ |@ TCF C/C++ Debugger 1.3.1.201505051438 
| |%% TCF Remote System Explorer add-in 1.3,0.201505261946 
& TCF Target Explorer 1.3.1.201504300712 
(7 |%% TM Terminal 4.0.0.201506040610 v| 
|__Selectall_} |_Deselectil | 1 item selected 
Details 




















\v| Show only the latest versions of available software | Hide items that are already installed 





ra 





Group items by category What is already installed? 





Show only software applicable to target environment 














a 





Contact all update sites during install to find required software 





® [<Back = [next>] [Finish —_| [peeCancel 

















Step through the following sections and when prompted to restart, accept yes. 
We are not ready to use it yet, we must add serial port support into Eclipse. 


Go back to Help > Install new software and add a new repository 
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Available Software 


Select a site or enter the location of a site. 





it 


8 
Work with: (jelexelaso (age Bsic 


Find more software by working with the “Available Software Sites" preferences. 























type filter text 








The repository URL is: 





. http://archive.eclipse.org/tm/updates/rxtx/ 











Name: http://archive.eclipse.org/tm/updates/rxtx/ 


Location: http://archive.eclipse.org/tm/updates/rxtx/| 


® 




















Now we can select the Serial port run-time support library: 
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Available Software | J 
Check the items that you wish to install. 


Work with: http://archive.eclipse.org/tm/updates/rxtx/ - http://archive.eclipse.org, v Add... 











type filter text 








Name Version 

» f |00 RXTX 2.1-7r3 

4 (0 RXTX 21-714 
& RXTX End-User Runtime 2.1.7.4_v20071016-7B57e7UAXMAAGGAGT 
 RXTX Extender SDK 2.1.7.4_v20071016-417C7DP1Bh_eEaQUBrHBHg 











Deselect All 1 item selected 


Details 





|¥| Show only the latest versions of available software Hide items that are already installed 
|v] Group items by category What is already installed? 


[| Show only software applicable to target environment 





(¥] Contact all update sites during install to find required software 
































Follow through the further navigation screens and restart Eclipse when prompted. 


We now have terminal support installed and are ready to use it. From windows > Show 
View > Other we will find a new category called "Terminal". 
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S show view scan 


& Java Browsing a | 

& LTTng 

& Make 

& Mylyn 

&& Oomph 

& Profiling 

&& Remote Systems 

& Team 

& Terminal 
Terminal 

& Tracing 


W 


a 








are) 

















Opening this adds a Terminal view to our perspective. There is a button that will allow 
us to open a new terminal instance that is shown in the following image: 

















fi. Problems | Tasks & Console [1 Properties #’ Search Terminal © Bs | ab | s 














Clicking this brings up the dialog asking us for the type of terminal and the properties. 
For our purposes, we wish to choose a serial terminal. Don't forget to also set the port 
and baud rate to match what your ESP8266 uses. 
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© Launch Terminal o [Cel x 









































Choose terminal: | Serial Terminal 4 

Settings 

Port: COM17 v 
Baud Rate: 115200 7 
Data Bits: 8 MA 
Parity: None wv. 
Stop Bits: 1 v 
Flow Control: |None mA 











Timeout (sec): 5 





Encoding: | Default (ISO-8859-1) a4 




















After clicking OK, after a few seconds we will see that we are connected and a new 
disconnect icon appears: 




















#2 Problems #) Tasks & Console [Properties # Search Terminal % &) st| ts Ee BB | rf 
&) Serial COM17 (7/19/15 6:41 PM) 











And now the terminal is active. 


You can invert the colors to produce a white on black visualization which many users 
prefer. 


Web development using Eclipse 

Eclipse also provides a first class web development environment for writing and testing 
web apps including HTML pages. It is suggested that the Eclipse Web Developer Tools 
be installed. 
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Programming using the Arduino IDE 

Long before there was an ESP8266 or ESP32, there was the Arduino. A vitally 
important contribution to the open source hardware community and the entry point for 
the majority of hobbyists into the world of home built circuits and processors. 


One of the key attractions about the Arduino is its relative low complexity allowing 
everyone the ability to build something quickly and easily. The Integrated Development 
Environment (IDE) for the Arduino has always been free of charge for download from 
the Internet. If a professional programmer were to sit down with it, they would be 
shocked at its apparent limited capabilities. However, the subset of function it provides 
compared to a "full featured" IDE happen to cover 90% of what one wants to achieve. 
Combine that with the intuitive interface and the Arduino IDE is a force to be reckoned 
with. 


Here is what a simple program looks like in the Arduino IDE: 


ESP Serial | Arduino 1.6.5 oS 


File Edit Sketch Tools Help 


ESP_Serial1 


1 void setup() (i = 
// put your setup code here, to run once: 


Seriall.begin(115200); 








1} 


void loop() { 
‘/ put your main code here, to run repeatedly: 


Seriall.printin("Hello! - millis() = " + String(millis())); 
9 } — 


Sj) on COM11 
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In Arduino parlance, an application is termed a "sketch". Personally, I'm not a fan of that 
phrase but I'm sure research was done to learn that this is the least intimidating name 
for what would otherwise be called a C language program and that would intimidate the 
least number of people. 


The IDE has a button called "Verify" which, when clicked, compiles the program. Of 
course, this will also have the side-effect that it will verify that the program compiles 
cleanly ... but compilation is what it does. A second button is called "up1caa" that, when 
clicked, what it does is deploy the application to the Arduino. 


In addition to providing a C language editor plus tools to compile and deploy, the 
Arduino IDE provides pre-supplied libraries of C routines that "hide" complex 
implementation details that might otherwise be needed when programming to the 
Arduino boards. For example, UART programming would undoubtedly have to set 
registers, handle interrupts and more. Instead of making the poor users have to learn 
these technical APls. the Arduino folks provided high level libraries that could be called 
from the sketches with cleaner interfaces which hide the mechanical "gorp" that 
happens under the covers. This notion is key ... as these libraries, as much as anything 
else, provide the environment for Arduino programmers. 


Interesting as this story may be, you may be asking how this relates to our ESP32 
story? Well, a bunch of talented individuals have built out an Open Source project on 
Github that provides a "plug-in" or "extension" to the Arduino IDE tool (remember, that 
the Arduino IDE is itself free). What this extension does is allow one to write sketches in 
the Arduino IDE that leverage the Arduino library interfaces which, at compile and 
deployment time, generate code that will run on the ESP32. What this effectively 
means is that we can use the Arduino IDE and build ESP32 applications with the 
minimum of fuss. 


Mapping from the Arduino to the ESP32 
Obviously, an Arduino is not the same thing as an ESP32 and as such, assumptions 
about the Arduino hardware don't map to the same things on the ESP32. 
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SPI MOSI 
Wire SCL 
Serial TX 
Serial RX 
Wire SDA 


(pu) 
svP 
SVN 


SPI MISO 
SPI SCK 
(pu) SPISS 


DAC1 
DAC2 





(pd) TDI ADC15 2 |i Cae) = | DC10 (pd) 
7 (pu) 

(pd) 
TDO (pu) 








Here we discuss some of the distinctions: 


¢ 1|2C and the Wire library — The default pins on the ESP32 for the I2C and Wire 
library are GPIO21 for SDA and GPIO22 for SCL. 


Implications of Arduino IDE support 

The ability to treat an ESP32 as though it were "like" an Arduino is a notion that | haven't 
been able to fully absorb yet. ESP32 is a Tensilica CPU unlike the Arduino which is an 
ATmega CPU. Espressif have created dedicated and architected API in the form of 
their SDK for directly exposed ESP32 APIs. The Arduino libraries for ESP32 seem to 
map their intent to these exposed APls. For these reasons and similar, one might argue 
that the Arduino support is an unnecessary facade on top of a perfectly good 
environment and by imposing an "alien" technology model on top of the ESP32 native 
functions, we are masking access to lower levels of knowledge and function. Further, 
thinking of the ESP32 as though it were an Arduino can lead to design problems. For 
example, the E needs regular control in order to handle WiFi and other internal actions. 
This conflicts with the Arduino model where the programmer can do what he wants 
within the loop function for as long as he wants. 


The flip side is that the learning curve to get something running on an Arduino has been 
shown to be extremely low. It doesn't take long at all to get a blinky light going ona 
breadboard. With that train of thought, why should users of the ESP8266/ESP32 be 
penalized for having to install and learn more complex tool chains and syntax to achieve 
the same result with more ESP8266/ESP32 oriented tools and techniques? The name 


Page 327 


of the game should be to allow folks to tinker with CPUs and sensors without having to 
have university degrees in computing science or electrical engineering and if the price 
one pays to get there is to insert a "simple to use" illusion then why not? If! build a 
paper airplane and throw it out my window ... | may get pleasure from that. ANASA 
rocket scientist shouldn't scoff at my activities or lack of knowledge of aerodynamics ... 
the folded paper did its job and | achieved my goal. However, if my job was to put a 
man on the moon, the ability to visualize the realities of the technology at the "realistic" 
level becomes extremely important. 


Installing the Arduino IDE with ESP32 support 
The Arduino IDE support for ESP32 can be found on Github here. 


https://github.com/espressif/arduino-esp32 


As of October 2016, this is an extremely new component and is still in the process of 
baking so be gentle with it. 


First we download and install an Arduino IDE at 1.6.9 or later. We then follow the 
installation/configuration instructions which are: 


1. Enter the Arduino installation directory 


2. Change into the "hardware" directory: 


S$ cd hardware 


3. Make a directory called "espressif": 


S$ mkdir espressif 


4. Change into the "espressif" directory: 


S$ cd espressif 


5. Download the ESP32 package for Espruino: 


S$ git clone https://github.com/espressif/arduino-esp32.git esp32 


6. Change into the "esp32/tools" directory: 


wy 


cd esp32/tools 


7. Run the supplied "get.py" script 
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S python get.py 


8. Start Arduino 


9. Pick "ESP32 Dev Module" from the Boards: 


Luyr our uu 










Arduino Pro or Pro Mini 
Arduino NG or older 
Arduino Robot Control 
Arduino Robot Motor 


Arduino Gemma a 


e ESP32 Dev Module 





Using the Arduino libraries as an ESP-IDF component 

Now comes the capability that excites me the most. By now we should be fully 
appreciative of the capabilities provided by the ESP-IDF and realize that it is component 
driven. This means that as we need functions, we can "drop them in" as components as 
long as they conform to the governance rules of the ESP-IDF. 


The Arduino libraries can be used as an ESP-IDF component. 


Let that sink in for a few moments. What this effectively means is that all the functions 
provided by the Arduino ESP32 libraries are available to us in our "normal" ESP-IDF 
applications. This is huge!! It opens up a world of possibilities for us. 


Now let us look at how we go about using the Arduino libraries in our project. Let us 
imagine that we have created a new ESP-IDF template application by using: 


S$ git clone https://github.com/espressif/esp-idf-template.git myapp 
Now we want to perform this recipe: 

1. Create a new directory called "components" in the app directory. 
S$ mkdir components 


2. Change into the components directory. 


S$ cd components 


3. Install the Arduino-ESP32 library relative to here by performing a Github Clone: 


S$ git clone https://github.com/espressif/arduino-esp32.git 


And that's it!! We can now build our sample application as normal. 
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Tips for working in the Arduino environment 

Remember that the Arduino environment is two things. First, an actual application that 
you install on your machine providing the Arduino IDE. Second, a set of libraries that 
model those available to an actual Arduino device which are mapped to ESP* 
capabilities. With that in mind, here are some hints and tips that | find useful when 
writing Arduino sketches for an ESP32 environment. 


Initialize global classes in setup() 

Within an Arduino sketch, we have a pre-supplied function called setup () that is called 
only once during ESP32 boot-up. Within this function, you perform one time 
initialization functions. In C++, we have the ability to create class instances globally. 
For example: 


MyClass myClass (123); 


void setup() { 
// Some code here 


} 
instead of this, use the following: 


MyClass *myClass; 


void setup() { 

myClass = new MyClass (123); 

// Some code here 
} 
This of course changes your variable's data type. It went from being an instance of 
MyClass to being a pointer to an instance of Myclass which means that you might have 
to change other aspects of your program ... but the reason for this is that in the first 
case, the constructor for your myclass instance ran outside of the setup() and we can't 
say what state the environment might have been in at that point. Within the setup () 
code, we have a reasonable expectation of the environment context. 


Invoking Espressif SDK API from a sketch 
¢ There is nothing to prevent you from invoking Espressif SDK API from within your 
sketch. You must include any include files that are necessary. Here is an 
example of including "xxxx.h". 
extern "C" { 


#include "XXXX.h" 
} 
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Notice the bracketing with the C++ construct that causes the content to appear as 
though it were being defined in a C program. 


Reasons to consider using Eclipse over Arduino IDE 

As previously mentioned, there is no question that the Arduino IDE is much more 
friendly and consumable that the professional Eclipse environment for folks new to the 
area. There doesn't appear to be anything that one can't build using the Arduino IDE 
that would mean one would have to switch to Eclipse. So why then would one ever 
consider using Eclipse? 


There is a trade-off between ease of use and richness of function. For example, Eclipse 
has built in syntax assistance, error checking, code cross references, refactoring and 
much more. None of these things are "essential" but any one of them can be 
considered to make a programming job easier if and when needed. If | need to rename 
a variable, in Arduino IDE | have to manually find and replace each occurrence. In 
Eclipse, | can re-factor the variable using a built-in wizard and the IDE does the work for 
me. As another example, if | can't remember the syntax for a method, in Arduino IDE | 
would go to the web and look it up while in Eclipse | could type the name of the method 
and hover my mouse over it and the tooling will show me the possible options for the 
parameters. 


Programming with JavaScript 

JavaScript is a high level interpreted programming language. Some of its core 
constructs are loose typing, object oriented, support of lambda functions, support of 
closures and, most importantly, has become the language of the web. If one is writing a 
browser hosted application, then it is a certainty that it will be written in JavaScript. But 
what of non-browser environments? For a while now JavaScript has been moving into 
server side code through projects such as Node.js. As a language for running server 
code, it has a significant set of features to realize this capability. Specifically, it supports 
an event driven architecture paradigm. In JavaScript, we can register functions to be 
called back upon events being detected. These callbacks can be defined as simple in- 
line functions on what to do. In these made up examples, we illustrate this: 


httpServer.on("/path1", function() { 
// Do something for /pathl 
httpServer.send(response) ; 

})3 





or 
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socket.accept (port, function(newSocket) { 
newSocket.on("receive", function(data) { 
print ("We received new data: " + data); 
newSocket.send("We got the data", function() { 
newSocket.close(); 
})e 
})e 
})e 





And if we can implement a good JavaScript model, it maps excellently to the ESP32 
model of the world which is itself event driven via callbacks. This mapping won't be 
easy ... but plans are afoot. 


The Duktape and Jerry Script engines provide excellent access to standard JS run- 
times. In addition Espruino is an open source project to provide a JavaScript run-time 
for embedded devices. It has been implemented for the ARM Cortex M3/M4 processors 
and others. 


The question now is ... can these be used for the ESP32? Active projects are 
attempting to do just that. 


See also: 


ESP32-Duktape 
Espruino 


Duktape 

Duktape is an open source implementation of JavaScript written exclusively in highly 
portable C with minimal footprint or requirements. It lends itself extremely well to 
running in embedded systems such as an ESP32. 


Being open source, one wondered if it would be able to build as an ESP-IDF component 
and ... yes it does. A project is now under way to provide a distribution. 


The core pattern for usage is: 

1. Create a context 

2. Evaluate JavaScript 

3. Delete the context 
We create a context by calling duk_ create heap default (). 
To evaluate a JavaScript string, we call duk_ eval _string(). 
To delete the context we call duk_destroy heap(). 
See also: 


duktape.org 
duktape API reference 
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Compiling code 
The JavaScript that is to be run can be executed in a variety of ways: 


* duk eval — Evaluate code on the stack. 


* duk compile — Compile code on the stack and leave it there as a function to be 
called. 


* duk compile lstring — Compile a string representation of JavaScript with a 
specific length. 











* duk compile file — Compile a file containing JavaScript. 


¢ duk_compile_Istring_filename — 


* duk compile string — Compile a NULL terminated string. 











* duk compile string filename — Compile a source file who's identity is on the 
stack. 


To invoke the code, we can either use one of the duk_eval() functions which compiles 
and executes or else we can compile and then invoke with duk_call(). 


Building for ESP32 
To our absolute delight, Duktape compiled first time using the ESP-IDF environment 
without any issues at all. 


Integrating Duktape in an ESP32 application 
To use Duktape in a C program we must include "duktape.h". 


We create a context for our JavaScript execute environment using 
duk_ create heap default(). 


The Duktape stack 

To work with Duktape C API is unusual relative to some other programming languages 
and concepts. It is based on a solid understanding of stack processing concepts such 
as push and pop and the stack frame in which we are working. 
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Working with object properties 

Imagine we wish to set a property on an object. First we push that object onto the 
stack. Next we push the name and then the value onto the stack. Finally we call 
duk_put_prop() and here is where the magic happens. The top two items are popped 
from the stack and considered to be the name and value. Next, the object given by its 
location on the stack from the top has a property created on it given by name and set to 
the value given by value. There are variants of this function including: 


* duk put prop — Pop the top 2 items and use as name and value. 


* duk put prop index — Pop the value from the stack and set to the property with a 
supplied index. 


* duk put prop string — Pop the value from the stack and set to the property with 
the supplied name. 


Let us imagine that we want to create a new object with properties. We would do this 
by: 


duk_idx t objIdx = duk_push_ object (ctx); 
duk_push_string(ctx, "Hello world"); 
duk_put_prop_ string(ctx, objIdx, "greeting"); 


The result will be a new object on the stack with the new property. 


We can retrieve values from the stack with duk_ get 2??? () functions. These are non- 
destructive retrievals. 


Calling C from a JavaScript program 
We can call native C function from a Duktape script. The functions must conform to the 
syntax: 


duk_ret_t myFunction(duk_context *ctx) { 
return 0; 


} 
A return of 1 means the top of the stack is to be interpreted as a return value. 


A return of 0 means that there is no return value and undefined is returned to the caller. 





A negative value means an error and should map to puK RET ???. 


To add a global function we would call: 


duk push global object (ctx); // Push the object into which we are going to set the 





function. 
duk_push_c_function(ctx, myFunction, argCount); // Push the function onto the stack. 
duk put _prop string(ctx, -2, "<functionName>"); // Set the object at top-2 to have a 


new function property. 
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JerryScript 

JerryScript is an open source implementation of JavaScript written exclusively in C with 
minimal footprint or requirements. It lends itself extremely well to running in embedded 
systems such as an ESP32. 


Being open source, one wondered if it would be able to build as an ESP-IDF component 
and ... yes it does. A project is now under way to provide a distribution. 


See also: 


jerryscript.net 

JerryScript & loT.js: JavaScript for loT from Samsung 
JerryScript mailing list 

Zephyr OS 

loT-JS 








Platform specific files 

When porting JerryScript to a new platform such as the ESP32, there are certain files 
that are environment specific. These can be found in the <root>/targets directory. 
The default directory has proven to work just fine. The functions that have to be 
implemented are: 


* jerry port fatal — Handle an error from which JerryScript can't recover. 
* jerry port console — Print to the console. 


* jerry port log — Display or log diagnostics. The options levels are: 





O° JERRY LOG LEVEL ERROR — 











O JERRY LOG LEVEL WARNING — 








© JERRY LOG LEVEL DEBUG — 


























O JERRY LOG LEVEL TRACE — 








° jerry port get time zone — 











°* jerry port get current time — 


JerryScript life-cycle 

To run a JerryScript JavaScript program we go through a life cycle that starts with a call 
to jerry init (). If we have a buffer that holds the JavaScript source, we then parse 
that source to create the environment suitable for execution. We do this by calling 
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jerry parse(). When we wish to run the code, we call jerry run(). To cleanup we 
Call jerry release value () against the parsed code and finally jerry cleanup(). 





To interpret code, we have an API call jerry eval() which takes a string of JavaScript 
and interprets it in the current context. The return is the value of the evaluation which 
may indicate an error has occurred. 


Accessing the global environment 
There is a special object that represents the full environment. We can obtain this 
through a call to jerry get global object (). 


The jerry_value_t 
The data type called jerry value t is the data type that references a JavaScript value. 
It can refer to: 


* boolean 

* number 

* null 

* object 

* string 

* undefined 


We can create a jerry value _t representing a string by creating one using a C NULL 
terminated string. For example: 





jerry value _t name = jerry create _string((const jerry char_t *)"John"); 
We can create a new object instance using jerry create object (). Given an object, 
we can set a property within that object using jerry set property(). 


A jerry value_t variable has a reference counter on it. Be sure and call 
jerry release value() when you no longer need a reference to it. 





A value also has an error flag which can be checked with 


jerry value has error flag(). 








Handling errors 
Errors encountered while parsing or running result ina jerry value _t which has an 
error flag associated with it. We can check that error flag with a call to 
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jerry value has error flag(). It is common that the resulting jerry value t 
corresponds to an object that has two properties: 





* name — The identity (name) of the error ... for example "ReferenceError" 
* message —An English description of the error. 


The generation of error messages is optionally compiled in and is off by default. To 
compile JerryScript with error messages, add 





-DJERRY ENABLE ERROR MESSAGES 


























to the compilation. 


Interfacing JerryScript with C 

From within a JavaScript program running in JerryScript, we can invoke a C function. 
This is a very important concept. It allows us to invoke arbitrary code such as ESP32 
specific functions such as WiFi enablement. 


The function that we wish to expose from C has to conform to a specific signature as 
defined by the jerry external handler t. 


jerry value_t myHandler ( 
const jerry value_t functionObj, 
const jerry value_t thisVal, 
const jerry value _t args[], 
const jerry length_t argsCount) 


The args is an array of arguments passed in. 
The argsCount is the number of arguments passed in. 


We register the function with a call to jerry create external function(). 





jerry value _t jerry create external function(jerry external handler t funcHandle) 


Here is a full example: 


static jerry value_t testFunction ( 
const jerry value_t functionObj, 
const jerry value_t thisVal, 
const jerry value _t args[], 


const jerry length_t argsCount) { 





ESP_LOGI (tag, "testFunction called!"); 
return 0; 








jerry value _t testF = jerry create external function(testFunction) ; 
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jerry value _t name = jerry create _string((const jerry char t *)"f1"); 
jerry value _t global object = jerry get _global_ object(); 

jerry set _property(global_ object, name, testF); 

jerry release value (testF) ; 





jerry release value (name) ; 
jerry release value(global object) ; 





// Now within the JavaScript we have a global function called f1() that 
// when it is called will invoke the C function called "testFunction". 


loT.js 

JavaScript is a powerful language but, like both C and Java, provides very little in the 
way of native libraries. The loT.js project provides an environment with a rich set of pre- 
built objects and classes that you can use in your JavaScript applications. 


See also: 


loT.js home page 


Programming with Python 


Pycom Micropython 
See also: 


Github: pycom/pycom-micropython 
YouTube: MicroPython ESP32 Building and loading firmware with Tony D! 








Programming with Lua 


Lua-RTOS for ESP32 
See also: 


Github: whitecatboard/Lua-RTOS-ESP32 





Integration with Web Apps 


HTTP Protocol 
The HTTP protocol is the underpinnings of all web based interactions including 
browser/web-server, REST requests and WebSockets. 
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HTTP Headers 

Following a HTTP request or response line, there will be zero or more HTTP headers. 
Think of these as name/value pairs that are used to pass additional information. Most 
HTTP headers are well document and architected into the standards while other 
headers can be used for application logic. 


Some headers are common to both requests and responses while others are found only 
on requests or only on responses. 


Accept header 
Used to indicate in a request the media types allowed in a response. The basic format 


is: 
Accept: <type>/<subtype> 

If we really don't care, we can specify the wildcards: 

Accept: */* 

However if we specify a type, we can wildcard the subtype: 

Accept: text/* 

or we can be explicit and define both type and subtype: 

Accept: text/plain 

Multiple entries can be supplied separated by commas. We can further qualify a type 
with a semicolon (";") followed by parameters. 


Authorization header 
Provides authorization credentials. Remember that unless we are using transport level 
encryption, these authorization credentials will be visible in a network examination. 





Connection header 
Used to indicate that the network connection should be closed by a request receiver 
after it has sent its response. 


Connection: close 


Content-Length header 
Used to indicate the size of the payload/content. 
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Content-Type header 
Used to indicate the type of data that is being sent in a request or response. 


Host header 
The Host header is mandatory on an HTTP/1.1 request and identifies who the 
transmitted claims to be. For example: 


Host: www. example -OLG 


User-Agent header 
A header that identifies the originator of the request. 





Web Servers 

A Web Server is a software component that listens for incoming HTTP requests from 
Web browsers. On receipt of a request, the web server sends a response. This can be 
the return of an HTML document for display in a browser or can be a payload of data 
that forms a service call response. An HTTP request can also include an incoming 
payload to send data into the ESP32 for processing. There are many implementations 
of Web Servers that can run within an ESP32 environment. 


See also: 


RFC7230 — HTTP/1.1 — Message Syntax and Routing 
HTTP: The Protocol Every Web Developer Must Know — Part 1 








Mongoose networking library 

The Mongoose networking library provides a library implementation and associated API 
that one can use to build a rich and powerful HTTP server. If we think about the core 
nature of a web server, we will find that it passively listens on a TCP port waiting for 
incoming requests. When a request arrives it services that request and then returns to 
its listening state waiting for the next request to arrive. The request is a text stream 
encoded in the HTTP protocol. The way mongoose works is to provide a framework 
following this model. We can tell mongoose to start listening and then when a request 
arrives, an event handler (a subroutine of code that we are responsible for writing) is 
invoked. The parameters to the event handler include the nature of the event (there are 
different types) and a parsed representation of the incoming HTTP request. For 
example, when a request arrives to retrieve a web page, the mongoose framework will 
call our event handler and tell us the path to the page being requested. Our code can 
then send back an HTTP response containing the file. Whether we get that data from a 
"file" or generate it via a dynamic call in code is immaterial. 
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To use the framework, we call mg _mgr_init() to initialize the environment. Next we bind 
it to a handler using mg _bind(). Finally, we poll the server for work using 
mg mgr poll(). 
void setupMongoose() { 

struct mg_mgr mgr; 

mg mgr init(&mgr, NULL); 

mg bind(&mgr, "80", evHandler) ; 

while(1) { 

mg mgr poll(&mgr, 1000); 

} 
} 
When a request arrives from a browser, we consider that an event which is handed off 
to an event handler. The signature of an event handler is: 


void eventHandler ( 
struct mg_connection *nc, 
int ev, 
void *evData) 


Where: 
* nc— The network connection that received the event. 
¢ ev-—The type of event that triggered the callback. 
* evData — Data associated with the event. 


Thus far we will receive callbacks for socket connections. If we wish, we can now 
register that we wish to parse the incoming data as an HTTP request. We do that by 
making a Call to mg_ set protocol http websocket(). For example: 


struct mg connection *c = mg _bind(&mgr, ":80", mongoose event_handler); 

mg_set_ protocol http _websocket (c); 

When setup as an HTTP server, an incoming browser request will appear with the event 
type of Mc_EV_HTTP REQUEST. The evData passed in will be an instance of struct 

http message from which the nature of the request can be determined. 

















Should we wish to setup debugging, we can compile with: 





* -DCS_ ENABLE DEBUG=1 — Specify if we want low level debugging. 














MG_EV event types we might see include: 
¢ MG EV ACCEPT 














* mG EV RECV — Data has been received. The ev data is a point to an int describing 
how many bytes of data were received. 


- MG_EV_SEND 
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- MG_EV_CLOSE 











* MG EV_HTTP REQUEST — Data Is an instance of a pointer to a "struct 
http message”. 














* MG EV_HTTP REPLY —Aresponse has been detected that is a response/reply to a 
previous HTTP request. Data is an instance of a pointer to a "struct 
http message”. 


The struct http message describes the nature of the message and contains: 
* message — The whole incoming message. The type is a struct mg str. 


* method — The method sent with the request ... eg. "cer". The type is a struct 


mg str. 





* uri-— The URI part of the request ... eg. "/hello". The type is a struct mg str. 
* proto 

* resp code 

* resp_status_msg 

* query_string 

* header names —An array of header names. The type is a struct mg str. 

* header values —An array of header values. The type is a struct mg str. 

* body — The body of the incoming request. The type is a struct mg str. 


To send a response when we have received a request, we will start by calling 

mg send _head(). This takes the status code, the length of the payload and any extra 
headers. To send the payload we will call mg send(),mg printf() Of mg vprintf(). 
Once all the data that we wish to send has been built, we should set the nc. flags value 
to include mG F SEND AND CLOSE to indicate that we have finished. 











Note that some of the string data types are coded as the special type "mg_ str" which is 
not the same as a null terminated string. Specifically, an mg_ str is a C structure that 
contains two fields: 


* p-—A pointer to data. 
* len — The length of the data. 
We have some utility functions to work with instances of mg_str including: 


° struct mg str mg _ mk _str(const char *s) — Make a new mg str from a null 
terminated string. 
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° struct mg str mg mk str _n(const char *s, size t len) — Make a new mg str 
from a pointer to data and length. 


* int mg _vemp(const struct mg str *strl, const char *str2) — Compare an 
mg_str against a null terminated string. 


* struct mg str mg _strdup(const struct mg_str s) — Duplicate an mg_str. 




















° struct mg str mg _strcemp(const struct mg str strl, const struct mg str 


str2) — Compare two mg_ str instances. 





To get a null terminated String from an mg_str, the following high level algorithm can be 
used: 


char *mgStrToStr(struct mg_str mgStr) { 


char *str = (char *)malloc(mgStr.len + 1); 
memcpy (str, mgStr.p, mgStr.len); 
str[mgStr.len] = 0; 


return str; 


} 
Here is an example mongoose event handler that is used to return the time since 
ESP32 start-up when /time is the path request. 


void mongoose event _handler(struct mg connection *nc, int ev, void *evData) { 
switch (ev) 
case MG EV_HTTP REQUEST: 


printf ("HTTP REQUEST\n") ; 



































struct http_message *message = (struct http_message *)evData; 
char *uri = mgStrToStr(message->uri); 
if (stremp(uri, "/time") == 0) { 


char payload[256]; 
sprintf (payload, "Time since start: %d ms", system_get_time()/1000); 
int length = strlen(payload) ; 
mg_send_head(nc, 200, length, "Content-Type: text/plain"); 
mg printf(nc, "ss", payload); 
} 
else { 
mg send _head(nc, 404, 0, "Content-Type: text/plain") ; 
} 
nc->flags |= MG_F SEND AND CLOSE 
free (uri); 
break; 








~ 


} 


The determination that the event is an HTTP request and the examination of the path is 
such a common occurrence that a helper function is provided called 
mg register http endpoint (). This function registers a relative URI path and an event 
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handler to be called when a request arrives that matches the path. This makes it easy 
for us to break out different paths. 


Since the ESP32 uses co-routines to provide an illusion of parallelism, this then asks 
the question about whether we can make mongoose API calls from multiple tasks. The 
answer is no. Instead we must invoke mg broadcast () to broadcast an event. The 
signature of mg_broadcast is: 


mg broadcast (struct mg mgr *, mg event handler t func, void *, size t) 
By default, this feature is disabled, to enable we have to add the following: 
CFLAGS+=-DMG_ ENABLE BROADCAST 

See also: 


Github: cesanta/mongoose 
Mongoose Developer Centre 
Mongoose WebSocket 





Setting up Mongoose on an ESP32 
The recipe | follow to setup Mongoose is as follows: 


1. In your project directory, create a components directory. 


2. Inthe components directory, clone Mongoose: 
git clone https://github.com/cesanta/mongoose.git 


3. In the new Mongoose directory, create a component.mk file containing: 


COMPONENT ADD INCLUDEDIRS=. 








4. Compile your solution. 


As you see there isn't much to it; it just works. 


Sending a request from Mongoose 
To send an HTTP request outbound from Mongoose we can use the mg _ connect _http() 


API. This has the signature: 
struct mg connection *mg_connect_http(struct mg_mgr *mgr, 
mg event handler t eventHandler, 
const char *url, 
const char *extraHeaders, 
const char *postData) 


The eventHandler Is a function that will be called to process events for this request. 
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JavaScript Webserver 

Running JavaScript on the ESP32 opens up some elegant techniques to serve web 
pages. Using JavaScript for web servers is discussed in the JavaScript section and not 
repeated here. 


See also: 


ESP32 Technical Tutorials: ESP32 Duktape WebServer 





The Mongoose struct mg_connection 
There are a number of fields/properties in the struct mg connection that might be of 
use to use. Here is a list of some of the more important/interesting ones: 





* union socket address sa — The address and port number of the other end of the 
network connection. We can use the mg conn addr to str() function to convert 
the mg_connection into a printable string. 





REST Services 

The notion of distributed computing dates back many decades. The idea that one 
computer could perform a service on behalf of another is a classic concept. The 
thinking is that work could be distributed across systems, data could be centralized or 
dedicated systems could perform specialized roles. Over the years, many forms of 
distributed computing have been tried. These include socket servers, remote procedure 
calls (RPC), Systems Network Architecture (SNA), Distributed Computing Environment 
(DCE), Web Services and others. 


Today (2017), the current incumbent of distributed computing protocols and technology 
is REST. REST is a simple protocol that leverages the existing Hyper Text Transport 
Protocol (HTTP) used as the transport between browsers and web servers. This 
protocol was build to allow a browser to request data from a remote file system hosted 
by a web server. It provides HTTP "commands" which include GET, POST, PUT and 
others. The notion behind REST is more of an accident than a design. REST re- 
purposes HTTP as a communication conduit from a client to a server where a client 
makes a REST request and the server offers up a REST service. From the network 
perspective, it "looks" just like a browser/Web Server interaction but both ends choose 
to agree on the formation and interpretation of the communication. 


When we add an ESP32 into the mix, our desire is two-fold. We want the ESP32 to be 
able to be a client to external REST service providers and we want the ESP32 to be the 
target of clients making REST requests. From the partner perspective, it should be 
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unaware that it is interacting with the ESP32 as compared to any other computing 
device. 


REST protocol 
The REST protocol is built on top of HTTP. 


See also: 


RFC7230 — HTTP/1.1 — Message Syntax and Routing 
HTTP: The Protocol Every Web Developer Must Know — Part 1 








ESP32 as a REST client 

For the ESP32 to be a REST client, it must build and transmit HTTP requests to the 
service provider. This will include building HTTP headers, transmitting the data in a 
form expected by the provider (eg. JSON, XML or other textual representation) and 

handling the response from the provider which may include interpreting the received 
payload. 


To transmit a REST request is composed of two parts. First it opens a TCP connection 
to the partner and then transmits the HTTP compliant data down that connection. The 
first part is easy, the second part is more of a challenge. We could read and understand 
the HTTP spec and build the request part by part but this would have to be done for 
each project that wishes to use REST client technology. What would be better is if we 
had a library that "knows" how to make well formed REST requests and we simply 
leveraged its existing functions. 


Making a REST request using Curl 
Not only is curl a command line tool, it is also a very rich library of function that can be 


used in your own projects. From an architectural perspective, any app that wants to use 
curl as a library should perform an initialization call, request an opaque "handle", setup 
parameters on the handle and then perform the request against the handle. The handle 
is a black-box that encapsulates the nature of the request. It hides from us all the low 
level details and gives us a higher level abstraction against which we can think of 
working with network endpoints. 


At a high level we call curl _global_init() for coarse initialization. Next we geta 
handle using curl easy init(). When we are finished with the handle we should call 
curl easy cleanup () to dispose of it and release any resources that may have been 
allocated on its behalf. The handle is the container that is used to associate options. 
We set options against a handle using curl easy setopt(). We will use this function to 
set the target URL at a minimum. 
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We can define a callback function that is invoked when data is received upon the 
handle. That callback function is registered against the handle. The signature of the 
callback function looks like: 





size_t writeData(void *buffer, size t size, size_t nmemb, void *userp) 


Think of this function as receiving a buffer of records where each record is of size bytes 
and the number of records is nmemb. Typically, size will be 1 and nmemb will then be the 
total size of data in the buffer. The function should return the size of data consumed. If 
itis not size * nmemb then that will stop processing. 


Once written, we can register the callback with: 


curl easy setopt (handle, CURLOPT WRITEFUNCTION, writeData) ; 





Notice that the data callback has a parameter at the end called userp. This is a pointer 
to context data that relates the request to the response. The value passed in to the 
callback function is the value registered with the handle using the cuRLOPT WRITEDATA 
parameter: 





curl easy setopt (handle, CURLOPT WRITEDATA, dataPointer) ; 





When ready, we can ask the handle to perform its task using: 





success = curl easy perform(handle) ; 


It is common that we want to pass HTTP headers with our request. To do this we build 
a list where each entry in the list is a name/value header entry. We use the data type 
struct curl _slist to hold the list: 


struct curl _slist *headers = NULL; 


To add a header we can then use: 


headers = curl slist_append(headers, "Content-Type: application/json") ; 


To associate the headers with a handle, we call: 








curl easy setopt (handle, CURLOPT HTTPHEADER, headers) ; 








When the list has served its purpose, we can release the resources used to manage the 
list with a call: 


curl _slist_ free all (headers) ; 


When making a REST request, we commonly wish to set the command in the HTTP 
payload. We can use the following to set different styles: 


To set the command to GET, use: 





curl easy setopt (handle, CURLOPT HTTPGET, 1); 


To set the command to POST, use: 


Page 347 


curl _ easy setopt (handle, CURLOPT POST, 1); 
To set the command to PUT, use: 
curl easy setopt (handle, CURLOPT PUT, 1); 


These commands will set the Content-Type to the form format. If we wish to send data 
as-is, don't call either of the above but just specify CURLOPT_POSTFIELDS data by 
itself. 


To send data with the request, we can use: 





curl easy setopt (handle, CURLOPT POSTFIELDS, data); 
Where the data is a null terminated string. 


The Curl package has a number of great samples. Here is a good instance that makes 
an HTTP GET request. 


#include <stdio.h> 
#include <curl/curl.h> 


int main (void) 
{ 
CURL: *curl; 
CURLcode res; 


curl = curl_easy init(); 

if(curl) { 
curl easy setopt (curl, CURLOPT URL, "http://example.com") ; 
/* example.com is redirected, so we tell libcurl to follow redirection */ 
curl easy setopt (curl, CURLOPT FOLLOWLOCATION, 11); 








/* Perform the request, res will get the return code */ 
res = curl_easy perform(curl); 





/* Check for errors */ 
if(res != CURLE_OK) 
fprintf(stderr, "curl_easy perform() failed: %s\n", 





curl easy strerror(res) ); 


/* always cleanup */ 
curl easy cleanup (curl); 


} 


return 0; 


} 


An excellent resource for testing Curl requests is the "httpbin.org" website. This 
provides HTTP rest responses for a variety of tests. 


To build libcurl we create a components directory and perform some commands within. 


The curl source can be downloaded from github using: 


S$ git clone https://github.com/curl/curl.git 
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Next we run: 


$ ./buildconf 
$ ./configure 


Remove the following from lib/curl_config.h 
HAVE_LIBSSL 
USE_OPENSSL 

HAVE_ZLIB 

HAVE_LIBZ 
HAVE_SIGSETJMP 
HAVE_SYS_ POLL 
HAVE_POLL 

HAVE_POLL_H 
HAVE_CLOCK_GETTIME_MONOTONIC 
HAVE _NET_IF_H 
HAVE_SYS_IOCTL_H 
HAVE_SYS_SELECT_H 
HAVE_SYS_UN_H 
HAVE_NETINET_TCP_H 
HAVE_MSG_NOSIGNAL 
HAVE_POLL_FINE 
USE_UNIX_SOCKETS 
HAVE_IFADDRS_H 
HAVE_STROPTS_H 
HAVE_GETIFADDRS 
HAVE_IOCTL_SIOCGIFADDR 
HAVE_GETHOSTNAME 
HAVE_GETEUID 
HAVE_BASENAME 
HAVE_SIGNAL 
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When building curl, we may need to set some definitions: 
The following can be found include/curl/curlbuild.h: 


* CURL SIZEOF LONG — 4 — The size in bytes of a long. 





* CURL TYPEOF CURL SOCKLEN T— unsigned int — The data type that is a 











socklen t. 





* CURL _TYPEOF CURL OFF T-— long 





* CURL FORMAT CURL OFF T— "1d" 














* CURL FORMAT CURL OFF TU— "lu" 





* CURL FORMAT OFF T—"%ld" 





* CURL SIZEOF CURL OFF T—4 





* CURL SUFFIX CURL OFF T-—L 

















: CURL SUFFIX CURL OFF TU—UL 
We also need a lib/curl_config.h 


We will also need a component .mk with the following entries: 


COMPONENT SRCDIRS:=1 ib 
COMPONENT PRIV_INCLUDEDIR:=lib include 
include $(IDF_ PATH) /make/component_common.mk 











We need to say that we don't have includes: 

* netinet/in.h -HAVE_NETINET_IN_H 

* arpa/inet.h - HAVE_ARPA_INET_H 

* net/if.n- HAVE_NET_IF_H 

* sys/ioctl.n -HAVE_SYS_IOCTL_H 

* process.nh - HAVE_PROCESS_H 

*  fcentl.n - HAVE_FCNTL_H 

* netinet/tcp.h - HAVE_NETINET_TCP_H 
To enable SSL, we add: 
#define USE_MBEDTLS 1 


And in the CFLAGS+=-DMBEDTLS _FS IO to both the CURL and the MBEDTLS 
component. 


See also: 


Curl 
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Curl C API 
curl_east_setopt 
ibcurl examples 


Making a REST request using Mongoose 

Using the Mongoose APIs, we can quite easily send a REST request and work with the 
response. The high level story is to initialize Mongoose with mg mgr _init(), requesta 
connection to the REST service provider with mg_ connect (), associate the connection 
as being HTTP oriented and then start processing events. The first event to return will 
be an Mc _ EV _coNNEcT event indicating that we are now network connected. From there 
Wwe Can USE mg printf () to send the REST request. When the REST partner responds, 
we will get an Mc_EV_HTTP REPLY event and we have completed our request/response 
pairing. 














ESP32 as a REST service provider 

For an ESP32 to be a REST service provider, basically means that it has to play the role 
of a Web Server and respond to Web Server requests. However, unlike a simple Web 
Server which simply retrieves and sends file content as a function of the path on the 
URL, it is likely that the REST service provider will perform some computation when an 
HTTP client request arrives. For example, if we attached a temperature sensor to the 
GP1Os of the ESP32, when a REST request arrives, the ESP32 could read the current 
temperature value and send the encoded result back as a the response to the request. 


Being a Web Server basically means listening on a TCP port and when connections 
arrive, interpreting the data received as HTTP protocol. This would be a lot of work on a 
project by project basis but thankfully there are a number of pre-written libraries that 
perform this task for us and all we need concern ourselves with is examination of any 
parameters passed with the request and performing the logic we wish performed when 
ever a new request is received. 


Once again, mongoose becomes an excellent consideration for being a Web Server 
and handling incoming requests. 


See also: 


Mongoose networking library 
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WebSockets 

WebSockets is both an API and a protocol introduced in HTML5. Simply put, if we 
imagine an HTTP server sitting waiting for incoming HTTP requests, we can convert a 
current request into a socket connection between the server and the browser such that 
either end can send data to be received by its partner. 


Here we see a raw request to upgrade an HTTP connection to a WebSocket 
connection: 
GET / HTTP/1.1 


Host: 192.168.1.10 
Connection: Upgrade 





Pragma: no-cache 

Cache-Control: no-cache 

Upgrade: websocket 

Origin: file:// 

Sec-WebSocket-Version: 13 

User-Agent: Mozilla/5.0 (X11; Linux x86 64) AppleWebKit/537.36 (KHTML, like Gecko) 
Chrome/46.0.2490.86 Safari/537.36 

Accept-Encoding: gzip, deflate, sdch 

Accept-Language: en-US,en;q=0.8 

Sec-WebSocket-Key: saim6TzFH+zVb4qY2nrh0Q== 
Sec-WebSocket-Extensions: permessage-deflate; client _max window bits 




















See also: 


html5rocks — Introducing WebSockets: Bringing Sockets to the Web 
The WebSocket protocol — RFC6455 
The WebSocket API 








A WebSocket browser app 

The highest likelihood is that you will be running your ESP32 as a WebSocket server. 
This would imply that you are going to have browser hosted applications that will be 
connecting to a WebSocket server as clients and from there, you will likely be writing 
some WebSocket client code ... if nothing else then for unit testing your server. 
Because of that, we will now spend some time talking about what is involved in writing a 
WebSocket client application. 


Let us assume that we will be writing JavaScript hosted in the browser. We start by 
creating an instance of a WebSocket object passing in the URL to the WebSocket 
server: 


var ws = new WebSocket ("ws://<somehost>[:<someport>]"); 


The WebSocket API is mostly event driven and there are a number event types of 
interest to us: 
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open — Invoked when the connection to the WebSocket server has been 
established and we are now ready to send or receive data. We can define this 
with the "onopen" property of the WebSocket as a function reference. 


message — Receive a message from the server. We can define this with the 
"onmessage" property of the WebSocket as a function reference. The incoming 
message data passed to the handler function contains a MessageEvent which 
contains: 


° data — The payload of the message. 


error — Receive an indication that an error was detected. We can define this 
with the "onerror" property of the WebSocket as a function reference. 


close — Receive an indication that a request to close the connection was 
detected. We can define this with the "onclose" property of the WebSocket as a 
function reference. 


Event handlers can be registered either with an "on<Event>" mechanism or with an 
addEventListener() Call. 








There are two methods defined on a WebSocket object. Those are: 


send — Send data to a WebSocket server 


close — Close the connection to a WebSocket server. The close() method takes 
two parameters: 


© close code — An integer close code describing the reason for the close. 
=# 1000 -CLOSE_NORMAL 
= 1001 —-CLOSE_GOING_AWAY 


o status message —A string describing the close reason. 


Finally, there are a few attributes: 


readyState — The state of the WebSocket connection. Values include: 
o WebSocket.CONNECTING 

o WebSocket.OPEN 

o WebSocket.CLOSING 

o WebSocket.CLOSED 


buf feredAmount — Amount of data that is buffered pending transmission to the 
WebSocket server 
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* protocol — The WebSocket server selected protocol being used. 


Mongoose WebSocket 

Using Cesanta's Mongoose libraries, we can setup a WebSocket server. After setting 
up a binding for incoming network requests we can call 

mg set protocol http websocket (). This will attach an event handler to the network 
protocol level to handle events associated with WebSockets. Specifically, these are the 
following events we are interested in: 








° MG_EV WEBSOCKET HANDSHAKE REQUEST — 


























° MG EV WEBSOCKET HANDSHAKE DONE — 





























° MG_EV_ WEBSOCKET FRAME — 
































When an Mc_EV_WEBSOCKET HANDSHAKE REQUEST Is received, the data contains a parsed 
HTTP request as a struct http message. When we receive the 

MG EVENT WEBSOCKET HANDSHAKE DONE event, we are ready to send and receive web 
socket messages. 





















































When an Mc _EV_WEBSOCKET FRAME Is received, the data contains a reference to a struct 
websocket_message. The struct websocket message contains: 








* data — The data passed from the partner. 
* size —The size of the passed data. 
* flags — Flags (unknown). 


To send outbound (out from Mongoose) web socket messages we use the 
mg send websocket frame() API call. The signature of this function is" 





void mg_ send _websocket_frame ( 
struct mg connection *nc, 
int op and flags, 
const void * data, 
size t data_len) 


The op_and_flags should be one of: 
¢ WEBSOCKET_OP_CONTINUE 
* WEBSOCKET_OP_TEXT 
* WEBSOCKET_OP_BINARY 
* WEBSOCKET_OP_CLOSE 
* WEBSOCKET_OP_PING 
* WEBSOCKET_OP_PONG 
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¢ WEBSOCKET_DONT_FIN — This can be boolean or'd with one of the above to 
indicate that we will be continuing. 


For example, if we wish to send a "Hello World" message we might code: 


char *message = "Hello World"; 














mg _send_ websocket frame(nc, WEBSOCKET OP_ TEXT, message, strlen(message) ); 








See also: 


Mongoose networking library 


Other Websocket implementations 
See also: 


WebSockets on the ESP32 





Tasker 

Tasker is an Android application that automates and scripts tasks to be executed on an 
Android device. Using Tasker we can create a task which is defined as a sequence of 
commands and actions to be executed. Next we can create a Profile which maps an 
event, that when detected, executes a task. Although this is useful, how does that 
relate to an ESP32? Imagine that the event that occurs is an ESP32 sending a 
message to your phone. With that notion, an ESP32 can, effectively, trigger anything 
that one might be able to do with such a phone. For example, it might make a phone 
call, send an SMS message or capture a photograph. 


See also: 


Tasker home page 
YouTube: Tasker 101 Tutorials 


AutoRemote 

Following on from our discussion of Tasker above, we now have an admission. It 
appears that Tasker does not have the ability to listen for incoming TCP/IP based 
events and messages. However, because Tasker is extensible and developers can 
write plug-ins for it, Tasker can be augmented. One such augmentation is the 
AutoRemote plugin. Using that plugin, a TCP/IP message can then be sent and 
received by AutoRemote which can then act as a source of events for Tasker. 


With AutoRemote configured as a Tasker plugin, we can configure it to listen for HTTP 
requests. This causes AutoRemote to listen on TCP port number 1817. The data it is 
listening for is an HTTP request. For example: 





http://<phone ip>:1817/sendmessage?message=1 
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With both Tasker and AutoRemote installed, it will still not be listening for incoming WiFi 
messages over a local WiFi environment unless we are Internet connected. We must 
run a Tasker Task called "AutoRemote WiFi". 


For example, in Tasker: 
1. Create a new profile triggered by Event — System — Device Boot 
2. Create a New Task associated with the profile 
3. Add an action from Plugin — AutoRemote — Wifi 
4. In the configuration for the action, check "Wifi Service" 
What this will do is start the Wifi Service whenever the device (Android) boots. 


Unfortunately, AutoRemote has a serious drawback. It doesn't allow Tasker to send a 
response back in the original REST request that might contain data that could be used. 
For example, if we wish to use AutoRemote to send a request that returned the current 
GPS location, that is simply not possible. 


When an AutoRemote request arrives, it sets a number of variables within the Tasker 
environment that can be used as parameters to Tasker tasks. These include: 


* %armessage 

* %arpar() 

* %arcomm 

* %artime 

° %arfiles 

¢ Y%arsenderbtmac 

* %arsenderid 

* Y%arsenderlocalip 
* %arsendername 

* %arsenderpublicip 


« Y%arsendertype 


* %arvia 
°. wifi 
See also: 





AutoRemote home page 
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DuckDNS 

| anticipate that in most folks houses there is a WiFi access point that either directly or 
through a modem, connects to the Internet. Since the WiFi access point offers a local 
network to which the ESP32 can join, we now see that the ESP32 can reach the outside 
world through the access point. However, what about the reverse? What if we want a 
client on the Internet to reach our ESP32. How could we achieve that? 


192.168.1.1 





173.194.115.36 Access 192.168.1.2 
Point 


ESP8&266 


If we look at the above diagram (all IP address made up), we see that the ESP32 knows 
its own IP address as 192.168.1.2. However, this can't be "shared" with the Internet as 
that is a local address and not a global IP address. What would need to be shared is 
the IP address of the access point as seen on the Internet. 


One way to achieve that is through the use of a service provider such as DuckDNS. 
This free service allows you to register aname. Your device (usually a PC) periodically 
sends a request to the DuckDNS web site saying "Hello ... | am here!". The return 
address implicitly sent with the request is always the IP address of your access point 
connected to the Internet and hence DuckDNS learns your external address. Later, 
someone (perhaps a third party) can ask "What is the IP address" of the name you 
registered and that address is made available. Essentially, DuckDNS acts as a real- 
time broker of logical names to IP addresses. 


If you are concerned that "some scary person" can learn the IP address of your access 
point ... then don't use DuckDNS. However, for the majority of us, our 
modem/router/access point prevents incoming traffic from reaching us and essentially 
blocks anything we don't want. But wait ... won't this also block requests to the ESP32? 
The answer is "yes it will" which is why you have to define port-forwarding. Port 
forwarding a function of your modem/router/access point that says that when a request 
arrives for a given port location, automatically forward it to an IP address on your local 
network ... for example, the network address of your ESP32. 
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https://www.duckdns.org/update?domains=XXxX&token=XxXxX&ip= 


Networking protocols 


MQTT 

The MQ Telemetry Transport (MQTT) is a protocol for publish and subscribe style 
messaging. It was originally invented by IBM as part of the MQSeries family of products 
but since has become an industry standard governed by the Oasis standards group. 
The latest specification version is 3.1.1. 


Being Pub/Sub, this means that there is a broker (an MQTT Broker) to which 
subscribers can register their subscriptions and publishers can submit their publications. 
Publications and subscriptions agree on the topics to be used to link the messages 
together. A client can be a publisher, a subscriber or both. 


The value of MQTT is that it can be used to deliver data from an application running on 
one machine to an application running on another. Immediately we seem to see an 
overlap between MQTT and REST calls but there are some major differences. Ina 
REST environment, when you form a connection from a client to a server, the server 
must be available in order for the client to deliver the data. With MQTT that is not 
necessarily the case. The client can publish a message which can then be held by the 
broker until such time as the receiving application comes on-line to retrieve it. This is a 
store and forward mechanism. 


Every published message must have a topic associated with it that is used to determine 
which subscribers would be interested in receiving a copy. 


The structure of a topic is broken into topic levels separated by a "/". Subscribers can 
include wild cards in their topic selections of copies of messages that they would like to 
receive: 


¢ +-— Single topic level wild-card 
€g. a/t+/c 
would subscribe to a/b/c and a/x/c. 
¢ # — Multi topic level wild-card 
eg. a/# 
would subscribe to a/<anything>. 


MQTT is commonly implemented on top of TCP/IP. Clients connect to the broker (not to 
each other) over a TCP connection. 


There is a quality of service requested by a client. This is encoded in the QoS field: 
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*  Qos=0 —Send at most once. This can lose messages. At most once means 
perhaps never. 


* QoS=1 — Send at least once. This means that the message will be delivered. 
Saying this another way, a message will not be discarded or lost. However, 
duplicates can arrive ... i.e. the message can be delivered twice or more. 


* Qos=2 — Send exactly once. This means that the message will not be lost and will 
be delivered once and once only. 


MQTT also has the capability to buffer messages for subsequent delivery. For example, 
if a client subscriber is not currently connected, a message can be queued or stored for 
delivery to the client when it eventually re-connects. We call a client that is not 
connected an off-line client. For a subscription, we have the choice to deliver all the 
queued messages for a client or just the last message. To understand the difference, 
we can imagine a published message that says "| sold your stock for <$$$> price" ... 
we want all such messages sent to the client because they are all of interest. However 
if we think of a published message of "Today's forecast is sunny and warm" then there 
may be no need for old messages and only the current weather forecast is of interest to 
us. During publishing we can declare that a message is eligible for retention and this is 
called the "retained message". When a client subscribes, it can ask to receive the last 
retained message immediately ... so even if a subscription takes place after a previous 
publication, it can still receive data immediately. 


Clients make their status known to the broker so the broker can tell if a client is 
connected. This is achieved via a keep-alive/heartbeat. When forming a connection to 
a broker, the client provides a keep-alive interval (in seconds). If the broker hasn't 
received a message from the client in this interval then the broker can disconnect the 
client assuming it to have been lost/disconnected. If the keep-alive interval is set to 0, 
then there will be no validation from the broker. 


If a client connection is lost because of a network disconnection, the broker can detect 
that occurrence. This is where we get morbid. We define this as the client having 
"died". In the real world, when someone dies, there may be a last "will and testament" 
which are the desired instructions of what the person wanted to happen when they die. 
MQTT has a similar concept. A client can register a message to be published in the 
event of the clients death. This is remembered by the broker and in the event of the 
client dieing, the broker will perform the role of the attorney and publish the last 
registered "will and testament" message on behalf of the deceased client. 


The default port number for an MQTT broker is 1883. 


See also: 
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MQTT Hive 
Mosquitto 


MQTT.org 

Oasis MQTT spec — 3.1.1 

Mosquitto.org 

YouTube: Internet of Things — Why You Need MQTT 
OASIS Message Queuing Telemetry Transport (MQTT) 
OASIS MQTT V3.1.1 Specification 














Mosquitto MQTT 
One of the most prevalent implementations of MQTT is called Mosquitto and is 
available as an open source implementation. On a Linux system we would install with: 


S$ sudo apt-get install mosquitto 


Where systemd is installed, mosquitto is controlled by it. To see if it is running execute 


S systemctl status mosquitto 
@® mosquitto.service - LSB: mosquitto MOTT v3.1 message broker 
Loaded: loaded (/etc/init.d/mosquitto) 
Active: active (running) since Thu 2016-01-21 21:32:26 CST; 6min ago 
Docs: man:systemd-sysv-generator (8) 
CGroup: /system.slice/mosquitto.service 
L12871 /usr/sbin/mosquitto -c /etc/mosquitto/mosquitto.conf 


Jan 21 21:32:26 kolban-VirtualBox systemd[1]: Starting LSB: mosquitto MOTT v3.1 
message broker... 

Jan 21 21:32:26 kolban-VirtualBox mosquitto[12862]: * Starting network daemon: 
mosquitto 

Jan 21 21:32:26 kolban-VirtualBox mosquitto[12862]: ...done. 

Jan 21 21:32:26 kolban-VirtualBox systemd[1]: Started LSB: mosquitto MOTT v3.1 message 
broker. 


The default configuration file for mosquitto iS /etc/mosquitto/mosquitto.conf. 
Messages from mosquitto are logged to /var/log/mosquitto/mosquitto.log. 


Two sample applications are provided that perform subscriptions and publications. 
These are mosquitto sub and mosquitto pub. These are distributed as part of the 
mosquitto-clients package. 


As a simple test, open two terminal sessions. In one run: 


$ mosquitto_ sub -t greeting 
When the subscriber is started it will sit quietly waiting for an arriving publication. 


In the other run: 


$ mosquitto pub -t greeting -m "Hello World" 
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Some other common flags we use with this command include: 

e -r-—Mark this publication as "retained". 

* -q 0/1/2—Set the Quality Of Service of the message. 

¢ -a—Include debugging in the output. 

* -h— Host (server) to connect to. Defaults to localhost. 

* -p—Port number to connect to. Defaults to 1883. 
You will see the published message appear in the subscriber window. 
Let us now dig a little further into a mosquitto configuration file. Within there, we can 
specify multiple "1istener" entries. These can bind to a port or a port and interface. 
Within a listener section, we can configure the protocol that the listener should use. By 
default, it will be plain TCP for normal client connections but we can specify that the 


protocol should be "websockets". For example, adding the following into the 
mosquitto.conf file: 

listener 8081 

protocol websockets 

will Cause mosquitto to listen for websocket clients on port 8081. If you want to listen on 
both standard matt protocol and websocket, then you will need multiple listener 
definitions. 


listener 1883 
protocol mqtt 


listener 8081 
protocol websockets 


See also: 


Mogsuitto.org 

man(1) — mosquitto_sub 
man(1) — mosquitto_pub 
man(5) — mosquitto.conf 
MQTT Community Wiki 














Installing on Windows 
We can download and install a version of Mosquitto for Windows. Binary downloads 
are available here: 





http://mosquitto.org/download/ 





The version illustrated here is 1.4.8. 


Page 361 





@ 


mosquitto Setup -o-| © [mee 


Welcome to the mosquitto Setup 
Wizard 





This wizard will guide you through the installation of 
mosquitto. 


It is recommended that you close all other applications 
before starting Setup. This will make it possible to update 
relevant system files without having to reboot your 
computer. 


Click Next to continue. 








Next > Cancel 








() mosquitto Setup [-c-| © [ee 
Dependencies Cua 
This page lists packages that must be installed if not already present ) 


OpenSSL - install 'Win32 OpenSSL vXXXxX Light’ then copy dils to the mosquitto directory 
http://slproweb.com/products/Win320penSSL.html 

pthreads - copy 'pthreadVC2.dll' to the mosquitto directory 
ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/dll/x86/ 





cone 
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Choose Components 
Choose which features of mosquitto you want to install. @ 








Check the components you want to install and uncheck the components you don't want to 
install. Click Next to continue. 





Descripti 
Select components to install: ame 
Position your mouse 
over a component to 
see its description. 
Space required: 461.0KB 














Nullsoft Install System v2.46 





Choose Install Location 
Choose the folder in which to install mosquito. @ 











Setup will install mosquitto in the following folder. To install in a different folder, click 
Browse and select another folder. Click Install to start the installation. 








Space required: 461.0KB 
Space available: 2.3GB 


Nullsoft Install System v2.46 
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(4) mosquitto Setup leco|)-f)-| 88 








Completing the mosquitto Setup 
Wizard 


mosquitto has been installed on your computer. 


Click Finish to close this wizard. 





Writing ESP32 MQTT clients 





Using Mongoose as an MQTT client 

Once again we can turn to Mongoose to provide higher level networking services. Not 
only can Mongoose be a Web Server and provide HTTP calling services, it also provide 
MQTT services. 

To be a client, at a high level we perform the following operations: 


mg mgr init(..); 
mg connect (...) ; 
while(1) { 

mg mgr poll (..); 
} 


In the event handler we registered in mg_connect (), we process events as follows: 
MG_EV_CONNECT 


mg_set_ protocol matt (..); 
mg_send_mqtt_handshake_ opt (...) 7 


MG_EV_MQTT_CONNACK 


// Do something now we are MOTT broker connected ... 
To publish a message we can Call mg_mgtt_publish(). 


To subscribe, we can call mg mgtt_subscribe(). The signature for a subscription is: 
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void mg_mgqtt_subscribe ( 
struct mg_connection *nc, 
const struct mg mqtt_topic_expression *topics, 
size_t topicsLen, 
uint16 t messageld) 


The mg mgtt topic expression Is a structure that contains two fields: 





* topic—char * — The identity of the topic on which to subscribe. 


* gos —uints t — The quality of service. 


Following a subscription, when a publication arrives, we will receive the 
G EV MOTT PUBLISH event. The payload of the event is an instance of an 
mg mgtt message which contains: 
































Type | Name Notes 
int | cmd 
struct mg_str|payload The payload of a received message. 
uint8_t/connack_ret_code | Used on MG EV_ MQTT_CONNACK. 
uint16_t/message_id Used on MG_EV_MQTT PUBLISH. 
char */topic The topic on which the message was received. 





Here is a concrete example: 


void event_handler mgtt(struct mg_connection *nc, int ev, void *evData) { 
switch (ev) { 
case MG EV CONNECT: 
mg_ set _ protocol mqtt (nc); 
mg _send_ mgtt_handshake(nc, "dummy") ; 

















break; 
case MG EV MOTT CONNACK: { 
struct mg_ mqtt_message *msg = (struct mg mqtt_message *) evData; 
if (msg->connack_ret_code == 0) { 
mg mgtt_publish(nc, "/greeting", 0, MG MOTT Q0S(0), "hello", 5); 
} 
break; 


} 
} // End of switch 
} // End of event handler mqtt 
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struct mg connection *nc = mg_ connect (é&mgr, "192.168.5.1:1883", 
if (nc == NULL) { 
printf("Error with mg_connect()\n"); 





} 
See also: 


Mongoose networking library 


Using Espruino as an MQTT client 


The Espruino JavaScript environment has native MQTT support. 


var ssid="RASPI3"; 
var password="password"; 


var wifi=require ("Wifi"); 
wifi.connect(ssid, {password: password}, function() { 
console.log("Connected to access point"); 
var mgtt = require ("MOTT") .create("192.168.5.1"); 
mqtt.on("connected", function() { 
console.log("MOTT connected") ; 
mqtt.subscribe ("test") ; 
mqtt.on('publish', function (pub) { 
console.log("topic: " + pub.topic); 
console.log("message: " + pub.message) ; 
})F 
})e 


console.log("Doing a connect") ; 





mqtt.connect (); 


b)F 
See also: 


Espruino MQTT 


Writing non ESP32 MQTT clients 


event handler mqtt); 


Having an MQTT environment available is nice but without clients doesn't add much 
value. Your clients will be the applications that will register subscriptions and publish 
messages. The subscriber will name the topic on which messages published will be 


received. 


While the MQTT protocol may be standardized, the client APIs appear to not be. As 


such there are multiple APIs for any given language. 


Eclipse paho 
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We start by creating a network representation object using NewNetwork(&n) followed by 
a connect to the host and port via NetworkConnect (). From there we have a number of 
MQTT primitives: 








QT 


QT 


QT 


QT 


QT 


QT 


QT 





QT 


TClientInit — Initialize a client. 
TConnect — Connect to an MQTT engine. 


TSubscribe — Subscribe to a topic and invoke a message handler when a 
subscription message arrives. 


TUnsubscribe — Unsubscribe from a topic. 
TPublish — Publish a message to a topic. 
TDisconnect — Disconnect from an MQTT server. 
TYield — Unknown. 


TRun — Run an MQTT client. 





The message handler passed to mottconnect () is invoked when a message is received 
by the MQTT client after it has been published to the broker. The handler function has 
the following signature: 


void function(MessageData *messageData) 


The MessageData data type is a C structure containing: 


MOT 


MOT 





TMessage *message — The message that was published. 








TString *topicName — The topic on which the original message was 


published. 


The mottTMessage data type is a C structure containing: 


enum QoS qos — The quality of service of the published message. 


unsigned char retained —A flag indicating whether this was a retained 


message. 


unsigned char dup —A flag indicating whether this message was attempted to be 
delivered previously and hence may be a duplicate. 





unsigned short id— The identifier of this message. 


void *payload—A pointer to the payload of the message. 


size_t payloadien-— The size in bytes of the message. 


Here is an illustrative client that takes a subscription: 
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See also: 


Paho home page 
Practical MQTT with Paho 





MQTTClientinit 
MQTTConnect 
MQTTDisconnect 
MQTTPublish 
MQTTUnsubscribe 
MQTTSubscribe 


C - Mosquitto client library 
The library called 1ibmosquitto is available for linking with C applications. You will need 


to install the package called 1ibmosquitto-dev. 
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mosquit 
mosquit 
mosquit 
mosquit 
mosquit 
mosquit 


mosquit 


mosqui 

















mosquit 
mosquit 


mosquit 


to bind 


mosquit 


mosquit 


mosqui 


mosquit 


mosquit 


mosqui 


mosquit 








TO _CONnNNect 


tO _ connect 


with 





tO _connect 





to lib version — Determine the version of the library in use 

to lib init — Initialize the library 

to lib cleanup — Conclude the use of the library 

to new — Create a client 

to_destroy — Destroy a client 

to reinitialize — Destroy a client and then create a new one 

to username pw set — Set the userid and password for authentication 
to will set — Set the last will of the client for estate planning purposes 


to will clear — Revoke the last will 


— Connect a client to a broker 


_bind— Same aS mosquitto connect but constrains interface 


_async — Asynchronous connection to the broker 


to reconnect — Reconnect to a broker after a lost connection 





to reconnect async — Same as mosquitto reconnect but asynchronous 
to disconnect — Disconnect a client from a broker 

to publish — Publish a message on a given topic 

to subscribe — Subscribe to messages on a topic 


to unsubscribe — Unsubscribe to messages on a topic 


* mosquitto loop — Perform processing for the mosquitto client. It is here that 
incoming message from the broker are received or previously unsent publications 


transmitted. 
* mosquitto loop read — 


* mosquitto_ loop write — 





* mosquitto loop misc — 





* mosquitto loop forever — Same as mosquitto_ loop but does not return and 


keeps processing until the client is disconnected 


* mosquitto socket — Retrieve the low level TCP/IP socket that the mosquitto 


client is using 


* mosquitto want write — Return true if there is pending data to be sent to the 


broker 


* mosquitto loop start — Start a thread to process a mosquitto_ loop inthe 


background 


* mosquitto loop end — Stop a previously started loop that was created using 











mosquitto_ loop start 


Here is an example publishing client: 


#in 
#in 
#in 
int 


Cc 


1 
c 
c 


3 


Ss 


i 


i 


clude <stdio.h> 
clude <string.h> 
clude <mosquitto.h> 


main(int argc, char *argv[]) { 
har *host="pc9100"; 

nt port = 1883; 

har *message = "hello world!"; 
har *topic = "greeting"; 


osquitto lib init(); 





truct mosquitto *mosq = mosquitto_new ( 














NULL, // Generate an id 

true, // Create a clean session 

NULL); // No callback param 
nt rc = mosquitto_ connect ( 

mosq, // Client handle 

host, // Host of the broker 

port, // Port of the broker 

false); // No keepalive 

£ (rc != MOSQ_ ERR SUCCESS) { 
printf("Error with connect: %d\n", rc); 





return(rc); 
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} 
mosquitto publish ( 


mosq, // Client handle 
NULL, // Message id 

topic, // Topic 

strlen (message) +1, // Length of message 


(const void *)message, // Message to be sent 
0, // QoS = 0 
false); // Not retained 
mosquitto destroy (mosq) ; 
mosquitto lib cleanup(); 


} 





See also: 


man(3) — libmosquitto 
mosauitto.h 





Node. js JavaScript - MOTT 
There is Node.js package called matt that provides MQTT functions for JavaScript 


applications. To install this package we should run: 


S$ npm install mqtt 


Here is a sample JavaScript application that acts as a publisher: 


var mgtt = require ("mqtt"); 

var client = mgtt.connect ("mqtt://pc9100") ; 

client.on('connect', function() { 
console.log("Connected ... now publishing") ; 


client.publish("greeting", "Hello from JavaScript"); 
client.end(); 


})e 


And here is an application fragment that acts as a subscriber: 


var mgtt = require ("mqtt"); 

var client = mgtt.connect ("mqtt://pc9100") ; 
client.on('connect', function() { 
client.subscribe ("greeting") ; 

})3 


client.on('message', function(topic, message) { 








console.log("Received message for topic=" + topic + ", message=" + message); 
})3 
Error handling can be accommodated by registering a client handler for an error event: 


client.on("error", function(error) { 
console.log("We detected an error: " + error); 
})3 
The full details of the API can be found on the NPM home page for the MQTT package. 
At a high level, the functions are: 





* connect — Connect to a broker. 
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* Client.publish — Publish a message. The message content may be a Buffer or 
a string. The identity of the topic on which the message is being published must 
also be supplied. 


* Client.subscribe — Subscribe to a topic. 








* Client.unsubscribe — Unsubscribe from a topic. The signature is: 


client.unsubscribe (topic, [options], [callback]) 


* Client.end— Close the client connection to the broker. 








* Client.handleMessage —-Amechanism for handling messages. 


See also: 


npm — matt 


Browser JavaScript - MOTT 

The Eclipse Paho project includes a JavaScript client API that is suitable for running 
within the context of a browser. This client API uses the HTML5 WebSocket API to 
communicate with an MQTT broker. 





Sensors 





MQTT 
Broker 


The MQTT broker chosen must support MQTT protocol through WebSocket. Popular 
brokers such as Mosquitto are able to perform that role. From a security standpoint, 
browsers are only allowed to make WebSocket requests back to the HTTP server from 
which the page running in the browser was originally loaded. As such, the browser can 
only make WebSocket requests to the MQTT broker if the MQTT broker served up the 
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page. We can alleviate that issue by introducing full function Web Servers and proxies 
into the story but for simple purposes, brokers such as Mosquitto can serve up static 
web pages directly. This means that we can point our browser to Mosquitto which will 
then look for an HTML file on the local file system to Mosuqitto and send that back to 
the browser. The browser will now see the MQTT broker as the server of the web page 
and when the JavaScript in that web page asks for an MQTT subscription, it will 
succeed. Within the Mosquitto configuration file, each listener definition that wishes to 
also provide HTTP files must supply an "http dir" option which names the directory 
that will be searched for HTML file requests from the browser. 


We are not limited running an MQTT broker on a separate server machine, we can run 
the MQTT broker directly on the Pi should we desire. 


Now let us look and see what is needed to run an MQTT client in the browser. 


First we need to download the Paho JavaScript client. If we visit the Paho downloads 
page: 
https://projects.eclipse.org/projects/technology.paho/downloads 





we will find an entry for "JavaScript client 1.0.1". Follow through that link and download 
the ZIP file. At the time of writing the result will be: 


paho.javascript-1.0.1.zip 


we can then unzip the file using unzip. Within we will find a file called mgttws31.4s. 
This is the JavaScript source of the client and needs to be included in the HTML file that 
will be using MQTT. Here is an example HTML with embedded JavaScript illustrating us 
connecting to a broker and registering a subscription. When a message is published to 
the matching topic, it is logged to the browser console. 








<html> 
<head> 
<script src="mqttws31.js"></script> 
<script> 
var client = new Paho.MQTT.Client ("192.168.1.101", 8081, "/", "CLIENT1") ; 
client.onMessageArrived = function(message) { 
console.log("Message arrived ...: " + message.payloadString) ; 





client.onMessageDelivered = function(message) { 
console.log("Message delivered ..."); 








client.connect ({ 
onSuccess: function() { 


console.log("On success ... we are now client connected to the broker!"); 
client.subscribe("greeting", { 
onSuccess: function() { 


console.log("Subscription success ..."); 


hy 


onFailure: function(context, errorCode) { 





console.log("Failed to make a subscription ... code=" + errorCode) ; 
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} 
})e 
ky 


onFailure: function(context, errorCode, rrorMesage) { 











console.log("On failure ... code=" + errorCode + ", message=" 4 rrorMesage) ; 
} 
})F 
</script> 
</head> 
<body> 
</body> 
</html> 


Within the mosquitto.conf file, we will have an entry that looks like: 


listener 1883 
protocol mqtt 


listener 8081 

protocol websockets 

http dir /mnt/pc/projects/robot 

This defines that we will listen on port 1883 for standard MQTT protocol while we will 
also listen on port 8081 for websocket HTTP requests and if a request to load a page 
arrives, we will serve it from a given directory. 


The API to publish a message is called "send" and takes as a parameter an MQTT 
message object. 


See also: 


Eclipse Paho JavaScript client 
Paho API JavaScript documentation 
The Mosquitto MQTT broker gets Websockets support 











CoAP - Constrained Application Protocol 

When we typically think of networked computers, we imagine our desktop PCs. These 
have powerful CPUs, lots of memory, networking cards and unlimited electrical power 
sources (they are plugged into power outlets). Even our cell phones and tablets aren't 
too dissimilar to these desktop PCs. Their CPUs are still relatively powerful, RAM is still 
measured in megabytes and when the batteries in these devices gets low (after many 
hours of usage) we think nothing about recharging them. 


With loT devices, characteristics change. We have limited CPU capabilities, very low 
memory availability and electrical power is at a premium. For these devices to 
communicate, every moment of radio transmission is a drain on power consumption. If 
our transmission unit of information is 1000 bytes we could consider that 1000 units of 
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consumption. If we could reduce that to a 100 bytes or 10 bytes would the potentiality 
to improve our power usage by a factor of 10 or 100 ... and that is important. 


If we think about common communication protocols like TCP/IP we will find that they are 
quite "chatty" and have relatively high overheads. If we go even further up the stack 
and start considering HTTP as a protocol, the overheads become extremely large. 
Layer on top of these other data such as JSON or XML ... and all of a sudden we find 
that the number of bytes we are passing for "control" and "structure" as compared to the 
actual content payload is grossly disproportionate. So ... why then do we use these 
protocols? The answer is standardization to achieve interoperability. We could invent 
any number of binary protocols that are solution specific but these, by definition, would 
have difficulty inter operating with each other. In addition, each time we wanted to 
leverage one of these protocols, we would have to go through some degree of learning 
curve. Nota great situation. 


Thinking this through, we find that what we ideally want is a standardized protocol that 
is designed to accommodate as many IoT use cases as possible but yet is designed 
from the ground up to minimize byte sizes for transmission and hence reduce radio "on 
time". Such a standard has been written and is called "The Constrained Application 
Protocol" or "CoAP". This standard has been issued as an IETF request for comments 
(RFC 7252) which adds credibility to the selection. Let us now look and see how this 
standard can be utilized in an ESP32 environment. 









































0 |1 (2/3 |4 |5 (6 |7 |8 |9 |0 |1 |2 13 4 [5 (6 |7 {8 |9 (0 1 2 |3 (4 |5 16 |7 (8 (9 /0 |1 
Ver T TKL Code Message ID 
Token (if any, TKL bytes) ... 




































































Options (if any) ... 
TJ} 1l}l}1}i)1j}i1 





— 


Payload (if any) ... 



































Ver: Version. Must be 0x01. 
T: Type of message: 
¢ Confirmable (0x00) 
¢ Non-Confirmable (0x01) 
¢ Acknowledgement (0x02) 
* Reset (0x03) 
TKL: Token length — A value between 0 and 8 (inclusive). 9-15 are reserved. 


Code: An 8 bit unsigned value that is coded in 3 bits (called the class) and 5 bits (called 
the detail). The class can be: 
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* request —0 

* success response — 2 

¢ client error response — 4 
* server error response — 5 


The options that follow are encoded for minimal space. While the encoding scheme is 
undoubtedly sensible to achieve minimum data size, it is worthless to describe its 
minutia here. Suffice it to say that there can be an arbitrary number of options of 
arbitrary length. Each option is represented by a numeric code and a value of zero or 
more bytes. There is a special "terminator" option type that can be used to terminate 
the sequence of options. 


See also: 


IETF REC 7252 — The Constrained Application Protocol (CoAP) 





FTP 

FTP is the File Transfer Protocol. On Linux we can install an FTP server using: 
S$ sudo apt-get install ftpd 

and we can install an FTP client using: 


S sudp apt-get install ftp 


TFTP 
A TFTP server can be installed on Linux using: 
S$ sudo apt-get install tftpd 


Wikipedia — Trivial File Transfer Protocol 
RFC1350 — The TFTP Protocol Rev 2 








Telnet 
An open source implementation of the telnet protocol is available on Github. 


When we think of Telnet, we should imagine an initial conversation between the client 
and the server where they negotiate the options that each supports. Each possible 
option is described by a struct telnet telopt_t which defines whether "we" support it 
or not and whether "he" supports it or not. If we support an option, we supply 

TELNET WILL and if not, we supply TELNET wont. If we require that the partner must do 
something we specify TELNET po otherwise TELNET DONT. 
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We initialize a telnet environment with a call to telnet_init(). This has the signature: 


telnet_t *telnet_init ( 
const telnet_telopts_ t *telopts, 
telnet event handler t handler, 
unsigned char flags, 





void *userData) 
The returned instance of telnet _t can be released with a call to telnet free(). 


On receipt of data from the partner, we pass that into the telnet environment with a call 
to telnet_recv(). This has the signature: 
telnet_recv ( 

telnet _t *telnet, 


const char *buffer, 
unsigned int size) 





To send a telnet command, we execute telnet _iac(). 
To negotiate an option, we use telnet _negotiate(). 
To send data, we use telnet _send() Of telnet _printf(). 


For sub-option negotiation we have the pair telnet begin _sb() and 


telnet finish subnegotiation(). 


Th event handler is an instance of a telnet event handler _t which is a function with 
the following signature: 








void handler(telnet_t *telnet, telnet _event_t *event, void *userData) 


A telnet event always contains a field called type which identifies what type of event it 
is. The choices are: 


¢ data 
° type 
o buffer 
° size 
* error 
° type 
© file 
°o func 
° msg 
° line 


° errcode 
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° jac 
° type 
° cmd 
* neg 
° type 
© telopt 
* sub 
° type 
© buffer 
° size 
© telopt 


The telnet types are: 





* TELNET EV_pDaTaA — Data received from the partner. 


























* TELNET EV SEND — Request to send data to the partner. 








See also: 


Github: seanmiddleditch/libtelnet 
RFEC854 
RFC855 





DNS Protocol 

The Domain Name Service protocol is responsible for resolving a domain name (eg. 
www.google.com) into the IP address that one should use to form a connection to that 
service provider. A TCP/IP network doesn't use string names but instead uses IP 
addresses which are typically 4 byte values. Since we humans don't want to try and 
remember these numbers there is the ability to provide a mapping from text names to 
those IP addresses. Servers located on the internet collaborate together to provide the 
mapping from names to addresses. Such servers are called "name servers". The 
protocol an application uses to resolve a name to a corresponding IP address in the 
DNS protocol. 


DNS servers typically listen on UDP port 53. When a local application has a domain 
name that it wishes to resolve to an IP address, it passes it to a local component 
logically called a "resolver". The resolver then works with distributed name servers to 
obtain the result. 
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When a UDP message is received by a DNS server, it has the following header: 





0 


1 2 3 4 5 6 











7 


8 


9 





10 





11 


12 





13 





14 





15 





ID 





QR 





OPCODE AA | TC 











RD 





RA 








RCODE 





QDCOUNT 





ANCOUNT 





NSCOUNT 








ARCOUNT 
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ar — Query/Response flag 





o Q-—query 

°o 1—response 
OPCODE 

° QO -—query 


o 1 -Jinverse query 

o 2-—server status request 
aa — Authoritative Answer 
° Q-no 

o 1-yes 

tc — Truncated Message 
° Q-no 

o 1-yes 

RD — Recursion Desired 
RA — Recursion Available 
z, — Reserved (must be 0) 


RCODE — Response code 





© Q-—no error 

©o 1 - format error 
o 2-—-—server failure 
o 3-—name error 


° 4-—not implemented 





o 5-—refused 


A Question section record has the format: 


QNAME — a repeating section 





°o Length byte = 0 for last entry 
© Label for length bytes 

OTYPE — 16 bits 

© 1—Host record (A) 

o 2-—NS record 





OcLass — 16 bits 


o 1 -—Internet 


A response should also contain the original request. 


An answer to a query is in the resource record format. The format of the record looks 


like: 


NaME — The domain name to which this record corresponds. This is the same 
format as the oname field. 








TYPE — Resource record type. 
o 1 -—IPv4 Address 

o others ... 

cLass — The class of data. 

o 1 -Internet 

o others ... 


TTL —A 32 bit unsigned supplying the seconds for which this record is valid for. A 
value of 0 means valid for this response but not to be cached. 








RDLENGTH — The size of rpata as an unsigned 16 bit value. 





RDATA — The data of the response. 


See also: 


DNS Protocol 
RFC1035 


Network sorcery — DNS protocol 
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Mobile apps 


Blynk 
Blynk is reported as being able to work with the ESP32 using the Arduino libraries. 
See also: 


Blynk home page 
Blynk — ESP32 
YouTube: thingSoC ESP32 with Blynk 





Cloud environments 

It is becoming increasingly common to leverage the services of a cloud hosted 
environment to process Internet Of Things (loT) based data. A cloud provider provides 
an end-point on the internet which is managed by the provider. It commonly accepts 
incoming data in a variety of protocols over a variety of transports and handles the data 
when it arrives. That could be as simple as storing it in a data store or could be more 
complex such as running a server side application on the received data. In addition to 
receiving the incoming data, some cloud environment provide the mechanics to manage 
an loT based device such as controlling its operation or pushing new firmware to it. All 
of this is done at scale. The number of devices and the amounts of data needing to be 
transmitted can be as high as needed. Vendors offer these cloud based services for a 
fee. After all, running a server and ensuring it is operational requires resources 
including time, staff and systems. In addition, to accommodate large volumes of huge 
number of devices, these vendors may be managing high end environments including 
network redundancy, transparent fail-over and "elasticity" in the provisioned services ... 
growing as needed and shrinking when idle. The fees charged by the vendors are 
commonly "metric" based fees charged as a function of how much resources you 
consumed. A customer with 100 devices with 1 message a minute per device doesn't 
consume the same resources as a customer with 100000 devices with 10 messages a 
second per device. Consult with the vendors for pricing. Typically, many offer 
evaluation access (you can play for free for 30 days) or constrained access (you can 
submit 100 messages a day). 


IBM Bluemix 

Bluemix is a quality offering from IBM that provides a wealth of cloud based capabilities 
including application hosting and much more. However, for our story, all we concern 
ourselves with is the loT portion. With a Bluemix account, one can create "loT 
Services" which run in the Bluemix cloud. These become the "end-points" of an loT 
client. For our discussions, such a client is an ESP32. When we configure a Bluemix 


Page 380 


loT service we start by defining a logical device type. This allows us to model the 
characteristics of our loT device and its properties. With a template of an loT device 
type created, we can then tell Bluemix that we have device instances. Each instance is 
created from the loT device type model and hence inherits its attributes. When we have 
modeled a device instance, Bluemix will supply us a security token which is a string of 
characters. When that actual device connects to Bluemix, the connection request will 
include the security token plus the identity name of the device. Bluemix will use this pair 
to validate that the device is who it claims to be. 


We can model each instance of physical ESP32 devices in this manner or, we can have 
each instance use the same device identifier. Flexibility is the name of the game. By 
giving each device its own device identifier, we can instruct Bluemix to "disallow" 
specific connections from specific devices should we choose. 


The messages sent by the ESP32 to Bluemix are based on the MQTT protocol so if we 
wish to write an ESP32 based Bluemix application, we would start by ensuring that we 
can publish MQTT messages. There are a variety of technologies to help us achieve 
that. 


If This Then That - IFTTT 

The notion behind the "If This Then That" technology is the simple concept of pairing 
sources of events with actions that can be performed. The If This Then That (IFTTT) 
web site allows anyone to pair together a trigger (a source of an event) and action (an 
action to be performed). The sources of events are rich ... extremely rich and there are 
hundreds to choose from. However, from the perspective of an ESP32 programmer, 
there is one source that stands out ... it is called "Maker". 





Once configured, we can send in a REST request with a JSON payload to a URL 
endpoint. The REST request includes: 


¢ The type of event we are submitting 
¢ Atoken that identifies the service we are targeting 
¢ Three optional parameter values 


Using this as a source of an event, we can then wire that into an action to be performed 
when such an event arrives. This takes us to the actions that can be performed by 
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IFTTT. Once again there are hundreds of choices to choose from including sending 
SMS messages, emails, tweets and more ... including making a REST request which 
itself could be targeted at an ESP32. 


See also: 


LERTT. 


Storage programming 

The notion of storage programming encompasses techniques for storing data for later 
retrieval or examination. The ESP32 has RAM but when the ESP32 is switched off, the 
RAM content is lost. As such we need a mechanism to make that storage more 
permanent. The ESP32 usually has access to flash memory that is electrically 
connected via a dedicated SPI bus. Typically the flash memory size is 32MBytes. We 
can access the flash memory through the SPI Flash APIs. 


See also: 


SPI Flash 


Partition table 

The ESP32 architects a concept called the partition table which is basically a "map" or 
"layout" of what is contained within the flash storage. The partition table is found at 
0x8000 In flash for a length of 0xcoo bytes providing space for about 90 distinct table 
entries. Each entry in the table has a record structure which logically contains: 


* type — The type of the partition. One of: 
°o data 
° app 
* subtype — The sub-type of the partition. One of: 
° nvs 
© phy 
© factory 
° coredump 
° ota 
* address — The address (flash) of the start of the partition. 
* size —The size of the partition in bytes. 


* label —An optional null terminated string (max 16 characters + NULL) 
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* encrypted -—Is the partition encrypted. 


The partition table is read-only to our applications and can be accessed with a rich API 
provided by the ESP-IDF. The table is written into flash storage by the flash tool. 


See also: 


Partition API 


Non Volatile Storage 

Non volatile storage is memory that can be written to such that after a power off or 
restart, the same data can be read from it again without loss. It is preserved over a 
restart. Within this data we can store configuration and operational values for our 
applications. For example, we might store the network SSID and password such that 
when the device is restarted, it know which network to connect to and the password to 
present. 


The storage is partitioned into named areas. For a given named area, we can then 
write name/value pairs to the storage and also read name/value pairs. There are 
getter/setter functions for most data types including signed and unsigned integers, 
strings and blobs of data. 


Anamed area is opened for access with a call to nvs_open(). The name of the area is 
passed in as a parameter. We are returned a logical "handle" that we can subsequently 
use to refer to this storage area. Once we have a handle, we can get/set items of 
named data. The data items are referenced by a key name ... effectively turning the 
storage area into a hash map. If we change data by performing a set function, this 
does not automatically cause the data to be written to the nonvolatile storage. Instead, 
the storage is updated when we call nvs_ commit (). It is up to the internal 
implementation as to when the actual update is performed and it could happen prior to 
nvs_commit(). The contract is that when we return from nvs_ commit () then we are 
assured that all updates have been processed. When we have done all our sets and 
gets, we should call nvs_close() to declare that we are not going to work with storage 
any more at this time so that the run-time can clean up any resources it may have 
opened. 


The details of the algorithms used to manage NVS are exposed in the documentation. 
The high level intent of NVS is to store simple strings and integers and other flags as 
opposed to be a rich "file system" like structure. There is currently no de-fragmentation 
performed on the storage. 


See also: 
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nvs_open 
nvs_commit 
nvs_close 


Virtual File System 

The Virtual File System (VFS) is the architecture provided by the ESP-IDF that gives us 
the capability of saving and loading data from our applications using a file system I/O. 
The VES isn't tied to any one particular technology but is instead an architectural 
abstraction used to provide the I/O interface to a variety of different implementations. 


The key to the VFS is a data type called esp vfs _t. This structure contains the 
following: 


fd_offset — 





flags — Operational flags. Use Esp vFs FLAG DEFAULT. 








close/close p— Close a previously opened file. 








closedir/closedir_p— Close a previously opened directory. 
Fstat/fstat_p — Get stats/details of a file. 


link/link p— Create a new link to a file. 





lseek/1seek_p — Change the data pointer within a file. 
mkdir/mkdir p — Create a new directory entry. 

open/open p— Open a named file. 

opendir/opendir p— Open a directory for reading. 
read/read_p — Read the contents of a file. 
readdir/readdir p—Read a record from a directory. 
rename/rename_p — Rename a file. 

rmdir/rmdir p — Delete a directory entry. 
seekdir/seekdir p-— Set the position of the next readdir(). 
stat/stat_p — Get stats/details of a file. 


telldir/telldir p— Return the current direction stream. 





unlink/unlink p — Remove a file. 


write/write p — Write into a file. 


After populating the structure, we need to register our new virtual file system with a call 
to esp vfs register(). 
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We need to be cognizant that the intended caller of file |/O expects a POSIX like 
environment. 


See also: 


esp_vfs_register 
Virtual filesystem component 





VFS Implementations 

Since the VFS provides an architectural model, we need to consider actual 
implementations of it. As of 2016-11, none are yet available. The first anticipated 
implementations will be file systems stored in flash. These will provide persistent 
storage of data through a file API. Potential implementations will include FAT or 
SPIFFS. 


We can also produce our own specialized implementations. One interesting idea is to 
allow the ESP32 to be a network client of external file systems. Possibilities include: 


¢ NFS 


- SSH 
- FTP 
- TFTP 


¢ HTTP servers 
¢ Google Drive 
¢ Other cloud based systems 


It may seem strange to have a network device access data through a file mechanism 

only to have it then farm out the requests as another network call ... however there may 
be benefits. The ESP32 could cache the received data either in RAM or local flash and 
only perform external network requests if the requested data is not available elsewhere. 


When working with file I/O, we can use the streams file mechanisms imported via 
"stdio.h" or use the lower level file I/O imported through "fcnt1.h". 


See also: 


VES mapping to SPIFFS 





FatFs File System 
The FatFs file system is an implementation of the FAT/exFAT file system as found in 
earlier PC operating systems such as MS-DOS and early Windows (before FAT32 and 
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NTFS). The implementation is open source and is supplied "pre-ported" to the ESP32 
as part of the ESP-IDF distribution. 


The ESP-IDF mapping for the FatFs maps the file system to the posix IO functions. 
This means that we don't need to learn any special APIs in order to read and write files. 
We can use open(), close(), read(), write() and the other methods exposed through 
Virtual File System. 


Before we can use these APIs, we need to perform some preliminary setup. 
1. Callesp_vfs_fat_register 
2. Call ff_diskio_register 


3. Call f_mount 


To unregister 
1. Close all open files 
2. Call f_mount with NULL 
3. Call ff_diskio_register with NULL 
4 


. Call esp _vfs_fat_unregister 


The FAT file system is primarily designed for working with SD cards as opposed to 
mapping a file system in flash memory. For memory mapped file systems, the 
recommendation is to use the SPIFFS file system. 


See also: 


FatFS — Generic FAT File System Module 
Virtual File System 
FatFs file system 





Spiffs File System 
The SPI Flash File System (SPIFFS) is a file system mechanism intended for 
embedded devices. To configure SPIFFs we need to determine some numbers. 


First is the physical page size. Next comes the physical block size. Next we decide on 
the logical block size. This will be some integer multiplier of the physical block size. 
The whole SPIFFS file system must be a multiple of the logical block size. Next comes 
the logical page size which is some multiplier of the logical block size. 


Acommon ESP2z2 sizing is 64K for the logical block size and 256 for the logical page 
size. 
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To be clear a 1 block is n x pages. 


When a SPIFFS API call is made, a Zero or positive response indicates success while a 
value < 0 indicates an error. The nature of the error can be retrieved through the 
SPIFFS errno() Call. 


The SPIFFS implementation does not directly access the flash memory. Instead, a 
functional area called a hardware abstraction layer ("hal") provides this service. A 

SPIFFS integration requires that three functions be created that have the following 
signatures: 


s32_t (*spiffs read) (u32_t addr, u32_t size, u8_t *dst) 

s32_t (*spiffs write) (u32_t addr, u32 t size, u8 t *src) 

s32_t (*spiffs_ erase) (u32_ t addr, u32 t size) 

If they succeed, the return code should be spirrs_ ox (0). On an ESP32, these will map 
to the SPI flash APIs. 


To use a SPIFFS file system, we must perform a call to sPIFFS mount(). This takes as 
input a configuration structure that tells SPIFFS how much flash is available and a 
variety of other properties. In addition, some working storage must be allocated for 
various internal operations. These sizes can be tuned. 


Here is an example of configuration for mounting a file systems: 











#define LOG PAGE SIZE 256 





static uint8 t spiffs_ work _buf[LOG PAGE SIZE*2]; 
static uint8 t spiffs fds[32*sizeof(uint32 t)]; 
static uint8 t spiffs_ cache buf[ (LOG PAGE SIZE+32)*4]; 


























spiffs fs; 

spiffs config cfg; 

cfg.phys size = 512*1024; // use 512K 

cfg.phys_ addr = 2*1024*1024 - cfg.phys size; // start spiffs at 2MB - 512K 
cfg.phys erase block = 65536; // according to datasheet 
cfg.log_ block size = 65536; // let us not complicate things 
cfg.log page size = LOG PAGE SIZE; // as we said 














cfg.hal_ read_f = esp32 spi flash_read; 
cfg.hal write £ = esp32 spi_flash write; 





cfg.hal_ erase f = esp32 spi_flash_ erase; 


int res = SPIFFS mount (éfs, 
&cfg, 
spiffs work buf, 
spiffs fds, 
sizeof(spiffs fds), 
spiffs cache buf, 
sizeof (spiffs cache buf), 
0); 
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Once we have mounted the file system, we can then open a file, write content into it and 
close it. For example: 


char *fileName = "/fl/my file"; 

spiffs file fd = SPIFFS open(&fs, fileName, 
SPIFFS CREAT | SPIFFS TRUNC | SPIFFS RDWR, 0); 

SPIFFS write(&fs, fd, (u8 t *)"Hello world", 12); 

SPIFFS close(&fs, fd); 





Similarly, if we wish to read data from the file we can perform the following: 


char buf[12]; 

spiffs file fd = SPIFFS open(&fs, fileName, SPIFFS RDWR, 0); 
SPIFFS read(&fs, fd, (u8_t *)buf, 12); 

SPIFFS close(&fs, fd); 


Using the 


The SPIFFS file system could be hierarchical in nature such that it contains both 
directories and files but it seems that in reality it is not. There is only one directory 
called the root. The root directory is "/". To determine the members of a directory, we 
can open a directory for reading with the spirrs_opendir() API and, when we are 
finished, close the reading operation with a sPIFFS closedir() API call. We can walk 
through the directory entries with calls to spIrrs readdir(). 


For example: 


spiffs DIR spiffsDir; 

SPIFFS opendir(é&fs, "/", &spiffsDir); 

struct spiffs dirent spiffsDirEnt; 

while(SPIFFS readdir(&spiffsDir, &spiffsDirEnt) != 0) { 
printf("Got a directory entry: %s\n", spiffsDirEnt.name) ; 

} 

SPIFFS closedir(&spiffsDir) ; 











To make this clear, in Linux, if we created "/a/b/c.txt" this would normally create a file 
called "c.txt" in a directory called "b" in a directory called "c". In SPIFFS, this actually 
creates a single file called "/a/b/c.txt" where the "/" characters are merely part of the 
file name. When we perform spirrs opendir(), there isn't actually a directory structure 
but just one single flat list of ALL files which may or may not have "slashes" in their 
names. 





To create a file, we can use the sPIFrrs_ open() API by supplying a spirrs creat flag. 


See also: 


SPIFFs API 

Github: pellepl/spiffs 

Github: igrr/mkspiffs — The mkspiffs tool. 
SPI Flash 

Virtual File System mapping to SPIFFS 
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Building SPIFFs for the ESP32 

Under the heading of "let's build on each other", an excellent job has been done of 
porting SPIFFs to the ESP32 by the LUA team (Jaume Olivé Petrus). The source code 
can be found: 


https://github.com/whitecatboard/Lua-RTOS-ESP32/tree/master/components/spiffs. 





They have packaged it as an ESP-IDF component. 


mkspiffs tool 

In addition to the fantastic SPIFFs library, there is also a tool called "mkspiffs" that can 
take a directory structure on your file system and build a SPIFFs image from it that can 
then be loaded into flash memory to provide pre-loaded data. 


One can download the Git repository for mkspiffs and compile it. | found no issues and 
it compiled at first go. 


The syntax is: 


mkspiffs { -c <packdir> | -u <destdir>|-1l|-i} \ 
-b <number> -p <number> -s <number> 


One of: 
* -c <directory to pack> 


* -u <dest to unpack into> 


« -l—list content 
¢« -j—visualize content 
and 


¢ -b <number> — Block size in bytes (for example 65536) 
* -p <number> — Page size in bytes (for example 256) 
¢ -sS <number> — fs image size in bytes. 


Visualizing an image file shows results such as: 


idid era_cnt: 
era_cnt: 








era_cnt: 





CoO O OO 


0 
1 
2 era_cnt: 
3 
4 


era_cnt: 
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5 era_cnt: 0 
6 era_cnt: 0 
7 era_cnt: 0 
8 era_cnt: 0 
9 era_cnt: 0 
10 era_cnt: 0 
11 era_cnt: 0 
12 era_cnt: 0 
13 era_cnt: 0 
14 era_cnt: 0 
15 era_cnt: 0 

era_cnt_max: 1 

last_errno: 0 

blocks: 1 

free blocks: 15 

page alloc: 4 

page delet: 0 

used: 1004 of 52961 

total: 52961 

used: 1004 


Once we have an image file, we can the load it to flash with: 


esptool.py --chip esp32 --port "/dev/ttyUSBO" --baud 115200 write flash -z 
--flash_mode "dio" --flash_ freq "40m" <address> <file> 
See also: 


Github: igrr/mkspiffs — The mkspiffs tool. 


The ESP File System - EspFs 

Part of the Github project known as "Spritetm/libesphttpd" is a module called "espfs" 
which is the "ESP File System". What this module does is allow one to make an image 
from a set of files on your PC and store that combined image in flash memory. From 
there, a set of APIs are provided to read and access those files and their content. It is 
vital to note that the data in these files is read-only. There is no API to update the 
content of the files. Only the data that is initially written to flash is available to be read. 


As part of the project there is a utility called "mkespfsimage" that takes as input a set of 
file names and streams as output the image data that should be flashed. For example: 


find | ./mkespfsimage [-c compressor] [-l compression level] > out.espfs 
(Note that the project has compression capabilities that | am ignoring at this point). 


Once the data is in flash, we can then use the APIs supplied by the component to 
perform the underlying data access. 


They are: 
* EspFslInitResult espFslnit(void *flashAddress) 
¢ int espFsFlags(EspFsFile *fh) 
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¢ EspFsFile *espFsOpen(char *fileName) 
* int espFsRead(EspFsFile *fh, char “buff, int len) 
* void espFsClose(EspFsFile *fh) 


An attempt to port the code to utilize ESP32 technologies was undertaken and can be 
found here: 


https://github.com/nkolban/esp32-snippets/tree/master/filesystems/espfs 





This adds a new function called: 
* int espFsAccess(EspFsFile “fh, void **buf, size_t *len) 


This function returns a pointer to the whole content of the file which is stored in buf. 
The length of the file is stored in 1en and also returned from the function as a whole. 
The data is accessed directly from flash without any RAM copies. 


In addition, the function called: 
¢ EspFslnitResult espFslnit(void *flashAddress, size_t size) 
was augmented to include the size of the flash storage to map. 


Here is an example application: 




















ESP _LOGD(tag, "Flash address is 0x%x", (int) flashAddress) ; 

if (espFsInit (flashAddress, 64*1024) != ESPFS INIT RESULT OK) { 
ESP _LOGD(tag, "Failed to initialize espfs"); 
return; 

} 

EspFsFile *fh = espFsOpen("files/test3.txt"); 

if (fh != NULL) { 


int sizeRead = 0; 

char buff[5*1024]; 

sizeRead = espFsRead(fh, buff, sizeof (buff)); 
ESP _LOGD(tag, "Result: %.*s", sizeRead, buff); 








size t fileSize; 

char *data; 

sizeRead = espFsAccess(fh, (void **)&data, &fileSize) ; 

ESP _LOGD(tag, "Result from access: %.*s", fileSize, data); 








espFsClose (fh); 
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SD, MMC and SDIO interfacing 

Secure Digital (SD) is a standard for removable media. These devices are also known 
as "flash cards" or "SD cards". The idea is that an SD card contains data that can be 
both read and written. The SD cards store the data as raw memory and it is common to 
create a file system that lives on top of the data. The FAT16 and FAT32 file system 
formats are commonly used. SD cards come in a variety of physical dimensions and 
with a variety of capacities and speeds. For the physical dimensions there are three 
distinct types known as "SD", "miniSD" and "microSD" ranging from largest to smallest. 
For capacity, there are again three distinct types known as "SD", "SDHC" and "SDXC". 























SD SDHC SDXC 
Capacity x <= 2GB 2GB <= x <=32GB 32GB <= x <= 2TB 
File system FAT12, FAT16 FAT32 exFAT 








For our story, we will ignore SDXC. 


An additional characteristic of SD cards is their rated speed. The common speeds are: 























Class 2 2MB/s 
Class 4 4MB/s 
Class 6 6MB/s 
Class 10 10MB/s 





The SD specification is large and comprehensive. If we were to try and implement the 
SD specification ourselves we would be delving down into a whole host of puzzles. As 
such, it is common to leverage pre-existing implementations of the specification and, 
thankfully, the ESP-IDF provides us with exactly that. 


There is also an excellent example application provide in the examples/storage/sd_card 
directory of the ESP-IDF. 


The SD card can be used to hold data but can not be used to hold instruction code for 
execution. As such, the SD card shouldn't be considered as an alternative to the flash 
memory accessible via SPI for code storage. The SD card should be used to store 
application data that can be read by or written by running applications. 


See also: 


Wikipedia: Multi Media Card 
Wikipedia: Secure Digital 








SD Association 
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Charting data 


Consider some of the sensors we have been discussing. By definition, a sensor reports 
on data that it measures. We can have our ESP32 perform actions based on the 
sensed data, however there are other things that we might want to do with that data. 
For example, using a temperature and pressure sensor, we almost immediately have a 
weather station and we might like to chart our data over time. This then leads us to 
think about different charting options available to us. 


The puzzle of charting data can usually be broken up into a set of distinct areas: 
1. Reading data from sensors. 
2. Recording / transmitting the sensor data. 
3. Drawing / updating the charts from the data. 


The first of these we won't discuss here. The reason for that is that the techniques for 
interacting with a sensor varies by sensor type and, as such, are wide and varied and 
covered elsewhere in this book. 


Once we have started reading data from the sensor, what are we to do with it? There 
are some obvious possibilities. The first is to save it locally on the ESP32 for 
subsequent retrieval or analysis. We can write our data into flash memory or into a 
micro SD card. This data can then be subsequently processed at a later time on the 
ESP32 or in the case of a micro SD card, the card can be extracted and placed in 
another reader. While this is of course of some use, the real beauty of the ESP32 is its 
ability to form network connections. If the ESP32 were to form a network connection to 
a some "consumer" of the data, then the data could either be extracted at a later time 
or, aS we are about to discuss, could be used to stream the data live from the device. 


If we read data from a sensor and have a TCP connection to the ESP32 from some 
external computer, the ESP32 could send the data down the TCP connection for 
consumption at the receiver. This way the ESP32 would not need to locally save the 
data as it is immediately off-loaded to the back-end computer. With cloud based 
technologies, we can choose a cloud provider and send the data there. Alternatively, 
we can use simple tools to get the data from Windows or Linux as the target of the 
ESP32 transmitted readings. 
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An example of such a tool is the Linux "netcat" launched through "nc". This can 
connected to an arbitrary IP/port pair and echos the data received to stdout. We can 
redirect the output to a file and we end up with a growing file of data. The ESP32 app 
reading from the sensor can then send the sensor data (perhaps formatted for output) 
down the socket and it will end up in the file. 


Kst 
The latest version of Kst is launched from Linux using "kst2". 


File Edit View 





l ew Range Create Mode Tools Settings Help 
mHCGCHHM SOC BXH® 0CO00O09O RM - H- T- 
30000 





T 






X Accel Y Accel Z Accel 


20000 


10000 


-10000 





| a nC CC 


-20000 


635000 640000 645000 650000 
Column 1 


2237 MB available 
See also: 


Kst home page 
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Sample Snippets 

There are times when all we need is a snippet of code that we can copy to achieve a 
task. Here we present a set of such snippets that may of use simply by copying and 

pasting them. A repository on Github has been created for hosting the snippets. The 
repository may be found at: 


https://github.com/nkolban/esp32-snippets 





Included in the repository are: 


¢ vfs/vfs-skeleton —A sample skeleton app for VFS 





Sample applications 

Reading and reviewing sample applications is good practice. It allows you to study 
what others have written and see if you can understand each of the statements and the 
program flow as a whole. 


Sample - Ultrasonic distance measurement 
The HC SR-04 is an ultrasonic distance measurement sensor. 





Send a minimum of a 10us pulse to Trig (low to high to low). Later, Echo will go 
low/high/low. The time that Echo is high is the time it takes the sonic pulse to reach a 
back-end and bounce back. 


Speed of sound is 340.29 m/s (340.29 * 39.3701 inches/sec). Call this V souna- 
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distance = d 
Sl 


rrr a! 


Tx / Rx Target 


Object 


If Techo is the time for echo response then d = (Techo * Vsouna) / 2. 


Also the equation for expected Techo lengths is given by: 
Techo = 2d/V sound 








For example: 
Distance Time 
lcm 2 * 0.01 / 340 = 0.058 msecs = 59 usecs 





10cm 


2 * 0.1 /340 =0.59 msecs = 590 usecs 








lm 





2 * 1 /340 =5.9 msecs = 5900 usecs (5.9 msecs) 








Because the Echo response is a 5V signal, it is vital to reduce this to 3.3V for input into 
into the ESP32. A voltage divider will work. The pins on the device are: 





@ Vcc — The input voltage is 5V. 


e trig — Pulse (low to high) to trigger a transmission ... minimum of 10usecs. 





@ cho — Pulses low to high to low when an echo is received. Warning, this is a 5V 
output. 


@ Gnd — Ground. 


To drive this device, we need to utilize two pins on the ESP32 that we will logically call 
Trig and Echo. In my design, | set Trig to be GPIO17 and Echo to be GPIO16. 
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ESP32 DevKitC 





HC-SR04 


thea 


Our design for the application will not include any networking but it should be 
straightforward to ass it as needed. We will setup a timer that fires once a second 
which is how often we wish to take a measurement. When the timer wakes up, we will 
pulse Trig from low to high and back to low holding high for 10 microseconds. We will 
now record the time and start polling the Echo pin waiting for it to go high. When it 
does, we will record the time again and subtracting one from the one will tell us how 
long it took the sound to bounce back. From that we can calculate the distance to an 
object. If no response is received in 20 msecs, we will assume that there was no object 
to detect. We will then log the result to the Serial console. 


An example program that performs this design is shown next: 


void mainThread(void *data) { 

gpio_pad_select_gpio(TRIG) ; 

gpio_pad_select_gpio (ECHO) ; 

gpio_set_direction(TRIG, GPIO MOD 

gpio_set_ direction (ECHO, GPIO MOD 

while (1) { 
gpio_set_level (TRIG, 1); 
ets delay _us(100); 


_ OUTPUT) ; 
INPUT) ; 








Fa. 
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gpio_set_level(TRIG, 0); 


uint32 t startTim 








while (gpio_get_ level (ECHO) 


(system get _time() 


} 








- startTime) 


= system _get_time(); 
// Wait for echo to go high and TH 





EN start the time 
0 && 


< 500 * 1000) { 


startTime = system_get_time(); 

while (gpio_get_ level (ECHO) == 1 && 
(system _get_time() - startTime) < 500 * 1000) { 
// Do nothing; 

} 

if (gpio_get_level(ECHO) == 0) { 


uint32 t diff = system _get_time() 


- startTime; // Diff time in uSecs 








// Distance is Timel 


double distance 


} else { 
// No value 


EchoIns 
340.29 * 
printf ("Distance is %f cm\ 


econds * SpeedOfSound / 2 
diff / (1000 * 1000 * 2); 
distance * 100); 


// Distance in meters 


" 
ney 





printf("Did not receive a 


} 
// Delay and re run. 
vTaskDelay(1000 / portTICK_P 


} 
Once this has been written and tes 


!\n"); 


respons 





ERIOD MS); 


ted, we will make a second pass at the puzzle but 


this time using an interrupt to trigger the response to the echo. 


See also: 


GPIOs 


Sample - WiFi Scanner 


A WiFi scanner is an application which periodically scans for available WiFi networks 
and shows them to the user. In our design, we will scan periodically and remember the 


set of networks we find. When we 
networks located is a network we h 
will also keep a "last seen" time for 
a minute, then we will forget about 
it to the user. 


perform re-scans, we will check to see if each of the 
ave previously seen and, if not, list it to the user. We 
each network and if a network has not been seen for 
it such that if it appears again, we will once more list 


To illustrate our design, we will break the solution into a number of parts. The first part 


will be to register a callback functio 


n that is called every 30 seconds. This callback will 


be responsible for requesting a WiFi scan using wifi station scan(). This takes a 
callback function which itself will be invoked when the scan is complete. 
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When the scan completes, we will have a new list of detected networks. We will walk 
this list and for each network detected, determine if we have seen it before. If we have, 
we will update the last seen time. If not, we will add it to the list of previously seen 
networks and log it to the user. 


A second timer callback will run once a minute and will walk the list of previously seen 
networks. If any of them are older than a minute, we will remove them. 


See also: 


Scanning for access points 


Sample - A changeable mood light 

NeoPixels are LEDs that are driven by a single data line of high speed signaling. Most 
NeoPixels have a +ve and ground voltage source as well as a data line for input and a 
data line for output. The output of one NeoPixel can be fed into the input of the next 
one to produce a string of such LEDs. The input data to the LED is a stream of 24 bits 
of encoded data which should be interpreted as 8 bits for the red channel, 8 bits for the 
green channel and 8 bits for the blue channel. Each channel can thus have a 
luminance value of between 0 and 255. By mixing the values for each of the channels 
together, you can color an LED to any color you may choose. After sending in a stream 
of 24 bits, if we send in a second stream of 24 bits quickly after the first stream, the 
second stream is "pushed" through to the next LED in the chain. This can be repeated 
as far as desired. If we pause sending in data, the current values are "latched" into 
place and each LED them remembers its own value. 


The timings of the data signals for these LEDs can be quite tricky but fortunately great 
minds have already built fantastic libraries for driving them correctly so we need not 
concern ourselves with these low level timings and can instead concentrate on devising 
interesting projects and purposes to which the LEDs can be placed. There area 
number of different types of these LEDs with the most common ones being known as 
WS2811, WS2812 or PL9823. 


Within the Espruino JavaScript environment, a method called neopixelwWrite() can be 
found. This takes two parameters. The first is the ESP32 GPIO pin that will be used as 
the source of the signals to the LEDs. It is to this pin that the LEDs should be wired. 
The pin used for data output from the ESP32 to the NeoPixels should be set in GPIO 
output mode. For example: 


pinMode (pin, "output"); 


The second parameter is an array of integers. The values of the array should be 
supplied in groups of 3 corresponding to the 3 channels of red, green and blue. For 
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example, if we had one NeoPixel connected to GPIO4 on an ESP32 and we wanted to 
set it to all red, we might code: 


neopixelWrite(new Pin(4), [255, 0, 0]); 





If we wanted the next pixel to be green while the first is red, we might write: 


neopixelWrite(new Pin(4), [255, 0, 0, On 25552 207 D6 





Again, there is no obvious limit to the number of LEDs we can string together. 


Now that we see that we can set the brightness and color of an LED, let us look at how 
we might design some code to do something. Let us imagine that we had a string of 16 
LEDs and wanted to make them the same color ... we might define a function as 
follows: 





function colorLeds(red, green, blue) { 
var data = []; 
for (var i=0; i<x16; itt) { 
data.push (green) ; 
data.push (red); 
data.push (blue) ; 
} 
esp8266.neopixelWrite (NodeMCU.D2, data); 


} 





If we call this function with the correct red, green and blue values, it will set the LEDs 
string correctly. 


Now let us go one step further. Imagine that we received a network REST request that 
described the color that we want the LEDs to show. A complete application may be: 





var esp = require ("ESP8266"); 
var NodeMCU = { 
// DO: new Pin(16), 

Dl : new Pin(5), 

D2 : new Pin 
D3 : new Pin 
D4 : new Pin 
D5 : new Pin 


D7 : new Pin 
D8 : new Pin 





D9 : new Pin 
D10 : new Pi 





(4) 
(0) 
(2) 
(14 
D6 : new Pin(12 
(13 
(15 
(3) 
n(1 


}; 


pinMode (NodeMCU.D2, “output"); 





function colorhLeds(red, green, blue) { 
var data = []; 
for (var i=0O; i<16; itt) { 
data.push (green) ; 
data.push (red) ; 
( 


data.push (blue) ; 
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} 


sp.neopixelWrite (NodeMCU.D2, data); 





function beServer() { 
var http require ("http") ; 
var httpServer 
print (request) ; 
var partsOfUrl 
if (partsOfUrl.length > 1) { 
partsOfUr1[1].split('&' 
{}; 
i<options.length; i++) 
options[i].split 


var options 

var optionsObj 

for 0; 
var splitEquals 
optionsObj [splitEquals[0]] 


(var i= 





fp" 
ay 





split 





} 

print ("Final obj: " + JSON.stringify ( 
if (optionsObj.color !== null) { 
parselInt (optionsObj.color 


var red 


http.createServer (function (request, 





response) { 


request.url.split("?"); 


)e 


{ 


"); 
quals[1]; 


optionsObj)); 


.substr(0,2), 16); 

















var green = parselInt (optionsObj.color.substr(2,2), 16); 
var blue = parseInt (optionsObj.color.substr(4,2), 16); 
print("red: " + red + ", green: " + green + ", blue: " + blue); 
colorLeds(red, green, blue); 
} 
} 
print ("Result url = " + url); 
response.writeHead(200, { 
"Access-Control-Allow-Origin": "*" 
})e 
response.end(""); 
}); // End of on new browser request 
httpServer.listen(80) ; 
print ("Now being an HTTP server!"); 
} // End of beServer 
var ssid = "ssid"; 
var password = "password"; 
// Connect to the access point 
var wifi = require("wifi"); 
print ("Connecting to access point."); 
wifi.connect (ssid, password, null, function(err, ipInfo) { 











if (err) { 
print ("Error connecting to access point."); 
return; 

} 

var ESP8266 = require ("ESP8266") ; 

print ("Connect says that we are now connected!!!"); 


print ("Starting web server at http://" + 
+ 28.0) 9 
beServer (); 


})e 


ESP8266.getAddressAsString (ipInfo.ip) 
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When this application runs, it connects to the local WiFI access point and then starts 
listening for incoming REST requests. A rest request is expected to have a query 
parameter at the end with the format color=value where value is encoded as 6 hex 
characters corresponding to the color. Finally, we can write a web page that will present 
a color picker and, when we pick a color, send a REST request to the ESP32 to 
illuminate the LEDs appropriately. Here is a sample web page to achieve this task: 


<!DOCTYPE html> 

<html> 

<head> 

<meta charset="ISO-8859-1"> 
<title>Set LED colors</title> 








<link 
href="http://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.11.2/jquery-ui.min.css" 
rel="stylesheet" type="text/css" /> 

<script 





src="http://cdnjs.cloudflare.com/ajax/libs/require.js/2.1.15/require.min.js"></script> 
<link rel='stylesheet' /> 
<script> 





href='spectrum.css' 


require 
.config({ 
baseUrl : 
paths : { 
"jquery" "http://cdnjs.cloudflare.com/ajax/libs/jquery/2.1.1/jquery.min", 
"Jquery-ui" : "http://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.11.2/jquery- 


Nera", 


i.min", 
}, 
shim: { 
"J query-ui" 
deps : [ 
exports: 


} 


{ 
"jquery" J, 
"JQueryUIL' 


} 
// End of shims 
})3 


require ([ 





"Jquery", "spectrum", "jJquery-ui" ], function(S$) 


$ (function ( 

var allow 

S("#flat" 
flat : 


preferredFormat : 


MOVve 3: 


if (a 


llowHttp) 
allowHttp 


{ 

Http = true; 

. spectrum ({ 
true, 

“rgb"™ s 
function(color) { 


{ 


false; 








S.ajax({ 


url.% 
data : 


"http://192.168.1.10", 
{ 


color : color.toHex () 


}, 


SUCCESS: 


{ 


function () 
allowHttp 


true; 


}, 
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error: function() { 
allowHttp = true; 
} 
})e 
} 
}, 
showInput : true, 
showButtons : false 
})e 
}); // End of on load 
}); // End of require 








</script> 
</head> 
<body> 
<div id="flat" style="width:500px; height: 500px;"></div> 
</body> 
</html> 


The end result as seen on the web page looks as follows: 





rgb(165, 46, 189) 


Selecting a new color causes the data to sent to the ESP32 which colors the LEDs 
appropriately with the over-all end result being the ability to change the mood light of the 
LED string. 


Using FreeRTOS 


When we think of a modern computer, we quickly realize that it has an operating system 
of some sort. Common examples of these are Microsoft Windows or Linux. The 
purpose of an operating system is to provide an interface between software applications 
and the underlying hardware infrastructure. If it wasn't for an operating system, each 
application would likely have to perform its own similar implementation of such functions 
which would be a waste. Why not write it once and provide an abstraction layer upon 
which higher level functions (such as applications) can be built. The capabilities of 
operating systems on PCs are very similar. They handle memory management, 
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hardware I/O (reading from keyboards and mice and driving graphics cards), task 
management (multiple programs running concurrently), disk and file system interactions 
and much more. Early operating systems provided basic functions while today’s 
operating systems have become richer and richer to the point where they may no longer 
be considered as just operating systems. Since when did an operating system need to 
provide Freecell or Minesweeper? 


If we rewind the clock and start again and look to the core aspects of an operating 
system, we come to today's FreeRTOS. FreeRTOS is an open source operating 
system that provides very basic functions to higher level applications ... again ... the 
core notion of the purpose of an operating system in the first place. However, 
FreeRTOS is designed for embedded systems such as the ESP32. It is orders of 
magnitude simpler than other operating systems such as Linux but this is by design. 


FreeRTOS has been ported to a wide variety of hardware platforms including the 
Xtensa CPUs used in the ESP32. When compiled, it results in a library that is under 5K 
Bytes in size. 


The core functions it provides are: 
* memory management 
* task management 
¢ API synchronization 


See also: 


Free RTOS home page 

Study of an operating system: FreeRTOS 
Github: espressif/ESP32_RTOS_ SDK 
Mastering the FreeRTOS real time kernel 











The architecture of a task in FreeRTOS 
Let us start with the notion of a task. A task is a piece of work that we wish to perform. 
If you wish, you can think of this as a C language function. For example: 
int add(int a, int b) { 

return a + b; 
} 
could be considered a task ... although this would be ridiculously simple. Generically, 
think of a task as the execution of a piece of C code that you have authored. We 
normally think of code running from its start all the way through to its end ... however, 
this is not necessarily the most efficient way to proceed. Consider the idea of an 
application which wishes to send some data over the network. It may wish to send a 
megabyte of data ... however it may also find that it can only send 100K at a time 
before it has to wait for the transmitted data to be delivered. In that story, it would send 
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100K and wait for the transmission to complete, send the next 100K and wait for that 
transmission to complete and so on. But what of those periods of time where the code 
is waiting for a previous transmission to complete? What is the CPU doing at those 
times? 


The chances are that it is doing nothing but monitoring the flag that states that the 
transmission has completed. This is a waste. In theory the CPU could be performing 
other work (assuming that there is in fact other work that could be performed). If there 
is indeed other work available, we could "context switch" between these work items 
such that when one blocks waiting for something to happen, control could be passed to 
another to do something useful. 


If we call each piece of work "a task", that is the value of a task in FreeRTOS. The task 
represents a piece of work to be performed but instead of assuming that the work will 
quickly go from start to end, we are declaring that there may be times within the work 
where it can relinquish control to other work (tasks). 


This can be illustrated pictorially in the following. First Task A is running and then it 
either blocks or else is preempted and Task B runs. It runs for a bit and then there is a 
context switch back to Task A and finally, Task C gets control. At any one time, an 
individual core is only ever running one task but because of the context switching, we 
achieve the effect that over some measured time period, ALL the tasks ran. 





With this in mind, we should think about how a task is created. There is an API 
provided by FreeRTOS called "xTaskcreate ()" which creates an instance of a task. 


Here it is important to realize that a task is a logical abstraction. There isn't anything 
specific provided in the CPU that knows what a task is. Instead, it is the operating 
system (FreeRTOS in our case) that is providing the model of the task for us. 


If we think deeply about a task, we can conceive of the task having a state. At any 
given time, either a task is running or it is not running. A task that is running is one that 
is actively using the CPU (i.e. not waiting for anything else to happen). A task that is not 
running is one that doesn't have the CPU. For example, if we created two tasks, one of 
them would be running and the other not running. If the one that is running reaches a 
point where it can no longer perform meaningful work, it will relinquish CPU control and 
become not running. The other task then has the opportunity to become running. 
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Going even deeper, when a task is not running, it may be "not running" for a particular 
reason ... such as: 


¢ Blocked waiting for something to complete 
* Suspended by the user 


¢ Ready to run such that when the task that is running is no-longer running, this 
task is eligible to become running 


In FreeRTOS we define a task as a C function that takes a void * parameter. For 
example, 


void myTask(void *myParameters) 
might be a signature for a task function. 


A task function is expected to run forever. Should it need to end, it should clean itself up 
before returning by invoking vtaskDelete(). 


When a task relinquishes control back to the OS, the OS then may have a choice 
between multiple tasks as to which one should become running. This selection process 
is called "scheduling". FreeRTOS uses the concept of a "priority" to determine which 
task to run next. Each task that is ready to run is considered a potential candidate and 
the one that has the highest priority will become the one that is running. 


When coding directly to FreeRTOS in non-ESP32 environment, one would normally 
have to make a call to vraskStartScheduler () to ensure that the task scheduler is 
operational. This should not be attempted in the ESP32 environment as the internals of 
the ESP32 environment have already registered other tasks and already started the 
scheduler. 

vTaskDelete 


xTaskCreatePinnedToCore 
YouTube: Tasks and concurrent Sockets 





Stacks and FreeRTOS tasks 
Consider a simple fragment of C code that has a couple of functions: 


int foo(int a, char b[200]) { 
Le. C7 
c = bar(a); 
printf("%Sd %s", c, b); 
return cc; 


} 


int bar(int d) { 
int e; 
e=da*d; 
relurn 
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Specifically, | want you to think about the variables in the functions. Hopefully we know 
that when we create a variable in C that the data that represents the value of the 
variable is stored in memory. For example, if | define an "int" variable, then 4 bytes of 
storage are required to hold that variable. If | define a variable as "char([200}", then 
200 bytes of storage are required to hold the maximum value of the variable. The 
question | pose to you is "where is the storage for those variables allocated?". 


The answer to that question is the idea of a "stack". A stack is a contiguous area of 
storage that contains the "local" or "contextual" variables of your currently executing 
function. For example, in the function foo shown above, the storage for variables "a", 
"pb" and "c" is created on the stack. Now let us consider what happens when f£o0() calls 
bar(). At the point when foo() Calls bar(), the address of the currently executing state 
is pushed onto the stack. This is subsequently used to determine where the called 
function will eventually return to. Next the parameter passed into bar() (i.e. "int a") is 
pushed onto the stack. Finally the storage for variable "e" is pushed onto the stack. 
Now we pass control to the compiled code that represents the entry point for bar (). 
Note that the stack has "grown" ... this means that the state of the data that was in 
place for foo() has not been lost ... only new storage has been added to provide the 
context for bar (). 


When bar () eventually returns, the stack allocated storage for the local context is 
deleted and we return to the stack structure that was in place at the point in £00 () 
where we were actually going to call bar (). We have "unwound" the stack. 


Here are some stack descriptions at different points in the life of our running program. 


First here is what the stack looks like within f00() just before calling bar (). 





inta 


char b[200] 








int c 











Next here is what it looks like just after calling bar () and while inside the bar () function: 





inta 


char b[200] 








int c 





return address into 
foo() 





int d 











inte 
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Notice that the stack held values for the function state of £00() have not been lost ... 
they are just further back in the stack. 


When eventually the code of bar() executes a return, we remove the state of bar () 
from the stack and return control to the address of the code within foo () that was the 
location where we called bar (). 





inta 


char b[200] 








int c 











This story repeats for arbitrary nested function calls. Each time we call a function, we 
are creating the local context of that function on the stack and passing control to the 
target entry point of the function. When the function returns we unwind the stack back 
to its state at the point of call. 


While all this is interesting, it feels a little academic for our work in ESP32s. Do we 
actually have to know this stuff? The answer is "sort of". In the ESP-IDF framework, we 
have the concept of "tasks" and each task can be thought of as its own thread of 
control. This means that, logically, there can be many functions executing in parallel to 
each other. Now let us map that to what we were just talking about relating to stacks 
and functions. Each task needs to have its own stack storage space. The variables in 
effect for one task are independent and isolated from the variables in effect for a 
separate task. Since a task can call arbitrary numbers of functions to an arbitrary depth 
and the amount and types of data can vary from one function call to another, the 
compiler doesn't know up-front how big the stack might possibly need to be. Instead, 
the decision of the amount of space to allocate for a stack for a given task is left to the 
programmer. If we look at the FreeRTOS API for creating a new task, we see that a 
parameter defines the amount of space to allocate for a stack for this specific task: 


BaseType t xTaskCreate ( 
pdaTASK CODE pvTaskCode, 
const signed portCHAR *pcName, 
unsigned portSHORT usStackDepth, // <----- Stack size defined here 
void *pvParameters, 




















unsigned portBASE TYPE uxPriority, 
xTaskHandle *pxCreatedTask) 


How big should you make the stack? The answer is a glib "big enough". Look at your 
application, estimate how much RAM your application needs to execute and then 
allocate some function of the remainder to the stack. 


If you size your stack too low, then the internal operation of the ESP-IDF will fail as it will 
wish to push more data onto the local task stack than there is space within that stack. 
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The good news is that is "trapped" and your program will stop and report the problem 


(as opposed to carrying on but broken). 


Timers in FreeRTOS 


There are a number of timer related functions within FreeRTOS that work on the notion 
of "ticks" where a tick is a unit of time. The default value of the FreeRTOS tick rate is 
100 times per second. This can be set in the "make menuconfig" settings found at: 


Component config > FreeRTOS > Tick rate (Hz) 





FreeRTOS 
Arrow keys navigate the menu. <Enter> selects submenus 
----). Highlighted letters are hotkeys. Pressing <Y> i 
modularizes features. Press <Esc><Esc> to exit, <?> for 
Legend: [*] built-in [ ] excluded <M> module < > 


[ ] Run FreeRTOS only 


(#100) Tick rate 
[* 
(1) Amount of thread local storage pointers 


eal 

[ ] Enable heap memory debug ---- 
(1536) ISR stack size 

[ ] Use FreeRTOS legacy hooks 

[ ] Debug FreeRTOS internals ---- 











core 
Xtensa timer to u s the FreeRTOS tick source 


] Halt when an SMP-untested function is called 
Check for stack overflow (Check using canary by 


FreeRTOS assertions (abort() on failed assertio 
Stop program on scheduler start when JTAG/OCD i 


modu 








While it seems that the ability to change the value is exposed, | would be wary in doing 
so. Arate of 100Hz means a tick every 1/100th of a second or every 10msecs. 


Rather than think of ticks as absolute numbers, we can thin of them as time durations 
relative to time. The duration of a tick can be specified as port TICK PERIOD Ms which is 
the duration of a tick in milliseconds. For example, if | need to wait for 1 second (1000 
msecs) then | would wait for 1000 / port TICK_PERIOD Ms ticks. 








Within FreeRTOS, we can block for a period of time using vTaskDelay(). This takes the 
number of ticks to wait until we unblock. Since the block affects only the current 


FreeRTOS task, other tasks will continue to be 


See also: 


xTaskGetTickCount 
xTaskGetTickCountFromlISR 
vTaskDelay 
vTaskDelayUntil 


eligible for execution. 
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Blocking and synchronization within RTOS 

With the notion of parallel processing tasks within RTOS, we must have a mechanism to 
synchronize actions between tasks. For example, imagine a task that produces data 
and a second task that consumes data produced by the first. The producing task must 
have a mechanism that describes that data has been produced and the consuming task 
must have a mechanism to block waiting for data to be produced. 


One way to achieve this is through the notion of an "event group". Think of an event 
group as a set of flags that can have the value "0" or "1". A task can set the value of a 
flag and a second task can be configured to wait (block) until a flag transitions from "0" 
to "1". What this means is that there is an asynchronous and loosely coupled 
communication through the use of these flags. From an implementation perspective, 
RTOS provides a data type called an "event group handle" that is implemented by the 
Opaque data type called "EventGroupHandle t". An instance of this is created through a 
Call to xEventGroupCreate(). We should assume that that an event group handle can 
contain a maximum of 8 distinct flags that are identified as 0 through 7. We can set the 
flags within an event group using xEventGroupSetBits() and clear flags using 
xEventGroupClearBits(). Should we need to obtain the values of an event group, we 
can Call xEventGroupGetBits(). Simply toggling bits isn't that useful, but we get into the 
core of the story with the xEventGroupWaitBits() function call. When invoked, it causes 
the caller to be blocked until a named bit or bits becomes set. 




















For example: 





static EventGroupHandle t eventGroup; 
#define EVENT GROUP_SCAN COMPLETE (1<<0) 


























void init() { 





eventGroup = xEventGroupCreate(); 





xEventGroupClearBits(eventGroup, Oxff); 


} 


void doSomething() { 
// Start something in the background and wait 





xEventGroupWaitBits (eventGroup, 
EVENT GROUP_SCAN COMPLETE, 
1, // Clear on exit 

0, // Wait for all bits 
portMAX DELAY) ; 


























} 





void backgroundEventHandler() { 
xEventGroupSetBits (eventGroup, EVENT GROUP SCAN COMPLETE) ; 





























} 
See also: 
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xEventGroupCreate 

xEventGroupSetBits 

xEventGroupWaitBits 

YouTube: ESP32 #25: FreeRTOS — Inter-task Communications — EventGroups 





Queues within RTOS 

A queue is a data container abstraction. Think of a queue as holding items. When an 
item is added to a queue, it is added to the end. When an item is removed from a 
queue, it is removed from the front. This provides a first-in/first-out paradigm. Think of 
a queue as the line of folks waiting at the department of motor vehicles. Folks join the 
end of the queue and those that have arrived earlier are serviced earlier. 


In FreeRTOS queues, all items on the queue are placed there by copy and not by 
reference. 


When a queue is created, the maximum number of items it can hold is set and fixed at 
that time. The storage for the queue is also allocated. This means that we can't run out 
of storage for the queues when adding new items. 


In RTOS we call xQueueSendToBack () to add an entry at the end of the queue. The 
consumer Calls xQueueReceive () to retrieve the person at the head of the queue. Items 
in the queue are always stored by copy rather than by reference. 


Attempt to receive from an empty queue can cause the caller to block. Conversely, 
attempting to add an item into a full queue can also cause it to block until space is freed. 


When we attempt to read an item from the queue and there is no item to read, the call 
to read will block. We can specify a timeout value measured in ticks. If no new 
message arrives in that interval, we will return with an indication that no message was 
retrieved. We can also specify 0 to return immediately if there are no messages. While 
a task is blocked reading from a queue that task is placed in the blocked state meaning 
that other tasks can run. This means that we won't be blocking the system while waiting 
on a queue. When a message arrives, the task that was previously blocked is returned 
to the ready state and becomes eligible to be executed by the task scheduler. 


See also: 


xQueueCreate 
xQueueCreateStatic 
vQueueDelete 
xQueueOverwrite 
xQueuePeek 
xQueueReceive 
xQueueReset 
xQueueSendToBack 
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xQueueSendToFront 
FreeRTOS Queues 
YouTube: ESP32 #20: FreeRTOS — Inter-task Communication — Queues 





Ring buffer withing RTOS 

Aring buffer is similar to the notion of a queue with a few major distinctions. Firstly, it is 
strictly first-in/first-out. There are no options to read from the head of the queue, only 
from its tail. In addition, new items can only be added to the head. While the RTOS 
queues have slots for a fixed number of items of equal size, the ring buffer can hold 
items with distinct sizes but all the items must exist within a configured size buffer. 


To create a ring buffer we call xRingbufferCreate() passing in the size of the buffer we 
wish to allocate (in bytes) as well as how we wish to handle items that may need to 
wrap-around. 


Calls can then be made to insert records of a given length into the buffer using the 
xRingbufferSend() function. Depending on our request and the way the buffer was 
created, if there is insufficient space in the buffer to insert the record, this call can block 
for a given period of time or indefinitely until space becomes available. 


Aconsumer that wishes to process records added to the buffer can call 
xRingbufferReceive() to obtain a record if one is available or else block until one does 
become available or a time interval elapses. It is important to note that a pointer to the 
storage of the record within the buffer is returned. This means that the record has NOT 
been removed from the buffer and its space has not yet been reclaimed. When the 
consumer has received a record and has finished processing it, the consumer should 
Call xRingbufferReturnItem() to indicate that it is no longer needed. At that time the 
storage for it will be released. 

xRingbufferCreate 

xRingbufferReceive 


vRingbufferReturnltem 
xRingbufferSend 


Working with queue sets 

What if we have multiple source of events such as multiple queues and semaphores? 
We could poll each one to see if it has data but this isn't efficient. FreeRTOS adds the 
concept of a "queue set". This is a set of items against which we wish to know when 
one of them becomes "ready". We use this by creating a queue set by calling 
xQueueCreateSet (). Next we add one or more watchable items using the 
xQueueAddToSet () API as many times as we wish. Now, when ready, we can call 
xQueueSelectFromSet () to ask the set if any of the previously added items are ready to 
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be read from without blocking. Effectively, we can block on all of these items 
simultaneously and the first one to have data ready for us will be acknowledged. 
xQueueCreateSet 


xQueueAddToSet 
xQueueRemoveFromSet 


Running untested functions 

Some of the FreeRTOS functions have not been tested as fully as necessary to be 
claimed "supported" by Espressif. What that means is that you should be cautious 
about using them in your applications. If using them causes failures, Espressif can't 
assure that a fix will be readily available. By the same token however, there are no 
known exposed functions that are known not to work. Again, this does not mean that all 
functions work, only that we have the absence of information about them. If you do use 
a function that is not flagged as supported, a run-time assertion will be deliberately 
thrown to cause you to consider not using that function. If you decide that you do wish 
to step off the path and use these un-tested functions, you can flag your desire to do so 
by changing a configuration flag set by "make menuconfig" within the "Component config 
— FreeRTOS" settings: 





[*] Run FreeRTOS only on first core 

Xtensa timer to use as the FreeRTOS tick source (Timer © (int 6, level 1) 
1000) Tick rate (Hz 

Halt when an SMP-untested function is called 

eck for stack overflow (Check by stack pointer value) ---> 

(3) unt of thread local storage pointers 

Fr TOS assertions (abort() on failed assertions) -- 
[*] Stop™grogram on scheduler start when JTAG/OCD is detected 
[ ] Enable heap memory debug --- 
(1536) ISR stack size 
[ ] Use FreeRTOS legacy hooks 
[ ] Debug FreeRTOS internals 











The Serial AT command processor 

Serial (UART) connections are one of the simplest ways to communicate directly 
between two physically located devices. With reasonably high speeds, two devices can 
connect easily. There are a variety of serial/USB connectors also on the market which 
means that your PC doesn't need to have a dedicated serial port. 


The ESP32 natively supports UART connections meaning that you can connect an 
ESP32 to your PC and have some application on the PC interact with the ESP32. 


Espressif, the markers of the ESP32, have produced a very high level application that 
can be downloaded and flashed to the device. This application is called the AT 
Command Processor. Its purpose is to send an receive ASCII serial commands over a 


Page 413 


serial link and process them. What kinds of commands? The answer is networking 
command. This means that the ESP32 can "off-load" networking from other devices. 
While it would be unlikely you would off-load networking from a PC, other devices such 
as for example an Arduino, could benefit from the simple off-loading of networking with 
the translation of such command to serial mappings. 


See also: 


ESP32 AT Instruction Set and Examples 





Developing solutions on Linux 
When working in a Linux environments, there are certain tips and techniques which 
might be useful/valuable. 


¢ When connecting to an ESP32 board using a USB—UART connector, the device 
may show up under /dev aS ttyusBO. If we examine the permissions upon this 
file, we may find that it is configured as: 





crw-rw---- root dialout 


This means that it is accessible by root and users in the dialout group. If you 
wish to flash the ESP32 through this device, your userid should thus be a 
member of this group. To add your user to the group, the following Linux 
command may be used: 


sudo usermod -a -G dialout <yourUserid> 
after making the change, you must log out and log back in again. 


¢ Auseful terminal client is ctkTerm. This tool provides a terminal viewer that can 
be used to monitor the USB—UART connector to view log and debug messages. 
It creates a configuration file in $HomE/.gtktermrc that can be edited to change 
the default serial port (eg. /dev/ttyusB0) as well as changing the baud rate to 
your desired value. 








¢ Another good terminal client is screen. Screen is a full screen terminal emulator. 


¢ Yet another terminal client is the classic cu command. Again, very easy to use. 
An example of use would be: 


S$ cu --line /dev/ttyUSBO --speed 115200 


To quit a cu session, enter "~.". 


Building a Linux environment 
If you don't run Linux natively you may wish to consider running Oracle VirtualBox to 
host a Linux environment on your Windows or Mac machine. Oracle VirtualBox is an 
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Open Source implementation of an operating system virtualization product. One can 
download VirtualBox from here: 


https://www.virtualbox.org/ 





In my tests, | ran Ubuntu 15.10. 


| define a disk size of at least 20GBytes and 2GBytes of RAM. If you have multiple 
cores, you may want to define those as being available. 


After building an image, make sure that you enable the ability to copy and paste 
between the host OS and the guest OS. 


_ — 

















£2) Video - Settings [2 | meen 
= General y General "A 

fe | System Basic | Advanced | Description | Encryption 

& Display Snapshot Folder: C:\Users\IBM_ADMIN\VirtualBox VMs\Video\Snapshots  v 
QZ Storage Shared Clipboard: [Bidirectional ~ | ise 

Drag'n'Drop: | Disabled nd 

Pe Audio 

al Network 

> Serial Ports 

@ uss 

- Shared Folders 

coma User Interface 

| Cancel Help 














Also make sure that the VirtualBox guest tools are installed. 


There are some packages that you really can't do without including: 
° git 
You can install new packages with: 


sudo apt-get install <package> 
Once you have a Linux OS installed, next we want to build a compilation environment. 


| would also install: 


Chrome 


See also: 
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Oracle Virtual Box 
Ubuntu downloads 


Hardware architecture 

The majority of this book describes programming the device at the software level 
through driver libraries. However, let us take a step back. The ESP32 is a low-level 
hardware component. It is basically a low level System On a Chip (SOC) device. 


The CPU and cores 
There are two cores within the ESP32 CPU named "PRO" and "APP". 


Intrinsic data types 

When we program in C, we are programming pretty close to the metal of the 
environment. Data type sizes and other considerations can and do come into 
consideration. Let us now examine the data sizes of some of the core types: 





























Type Size (bytes) Size (bits) 
short 2 16 
int 4 32 
long 4 32 
long long 8 64 
int64 t 8 64 
float 4 32 
double 8 64 














Native byte order, endian and network byte order 

When we wish to represent a number, for example 9876 (in decimal) we find that it will 
not fit in a single byte since a byte can hold only 8 bits of data and hence has a value 
from 0-255. As such, we need to split it across multiple bytes. If we think of two bytes, 
that is 16 bits of information and hence can represent a number from 0-65535. When 
we think of a 16 bit number we can think of that as two 8 bit numbers such that the 
resultis a * 256 + b. For example 9876 is 38 * 256 + 148... and in our equation a=38 
and b=148. No great mystery yet. Now we can see that a 16 bit number can be 
represented by two distinct 8 bit numbers. Now imagine a piece of memory where we 
wish to store our 16 bit number. We can immediately see that we will store our 16 bit 
number as two consecutive bytes. One byte representing "a" and one representing "b". 
The question becomes should we store "a" then "b" or "b" then "a"? From an underlying 
technical perspective both are equally valid ... however we need to be consistent across 


Page 416 


our architecture. Storing "a" then "b" is called a "big endian" architecture while storing 


">" then "a" is called a "little endian" architecture" 





a b 

















or 























Here is a simple program fragment to test for ourselves what is in play in the ESP32 
environment: 


char *p = malloc(2); 
*(unsigned short *)p = (unsigned short) 9876; 
printf ("low: $d high $d\n", *(p), *(ptl)); 


And when we run, the result is: 


low: 148 high 38 


Showing that the byte ordering for storing integers is "little endian". This concept 
becomes exceptionally important when reading binary data that was written on a 
different system. If we do not handle this correctly, we can interpret data in an incorrect 
fashion. For example 38*256+148 is a very different number from 38+148*256. 


Note that network data transport uses big endian format which means that the data 
format for native data on an ESP32 is not the same format as network byte order which 
means that we must transform data using htons(), htonl(), ntohs() and ntohl(). 


Amore precise terminology for byte ordering uses the phrases "Most Significant Byte" 
and "Least Significant Byte". With big endian encoding, the most significant byte is first 
while with little endian, the least significant byte is first. 


Memory mapping and address spaces 

When we program to the APIs exposed by Espressif provided libraries, we are taking 
advantage of the higher level APIs and internals that they expose. But let us now 
contemplate how those libraries work and what we can do with that knowledge. 


As a SOC, there is a processor (well, actually two of them), RAM and an address 
space. Being a 32 bit processor, the address space of the ESP32 is 32 bits in length. 
This means that, in theory, an application can read or write a byte at memory location 
0x0000 0000 Or Oxffff £ffFf Or any address in between. At the hardware mapping 
level, some of these addresses are mapped to RAM, some to an internal ROM, some to 
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peripherals and some to flash memory. By consulting the ESP32 Technical Reference 
manual, we can start to learn more. 


0x0000 0000 
Ox3F3F FFF 






0x3FCO 0000 
Ox3FEF FFFF 


Peripheral 


Ox3FFS 2000 
Ox3FFS FFFF 












RTC 
SLOW 
Memory 


Internal Internal 
ROM SRAM 


Ox3FFA 0000 


0x4006 0000 
0xd006 FFF 


0x40Cc0 0000 
Ox4FFF FFFF 


0x5000 2000 
OxFFFF FFrr 





Within the ESP32 there are four segments of internal memory: 
* ROM — 448KB — Read only memory with the content provided by Espressif. 
¢ SRAM — 520KB - Internal RAM that is supplied inside the ESP32. 
¢ RTC FAST — 8KB 
* RTC SLOW - 8KB 


There is also external memory. This is memory that can be addressed but that is 
provided by components outside of the ESP32 IC itself such as SPI flash or SPI ram. 
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The architecture of an ESP32 is called the "Harvard Architecture" and we need to 
explain that a bit more. When we think of a classic architecture, we usually think of the 
existence of a memory bus that reads and writes from RAM based storage. Both 
instructions and data can be found in the memory. The CPU retrieves the next 
instruction by requesting the data at a specific RAM address. When the instruction is 
retrieved, the CPU executes the instruction which may read or write data at other 
addresses in RAM. When the instruction completes, the story repeats for the next 
instruction. 


The Harvard Architecture introduces a second memory bus. The thinking is that RAM 
will either be used to hold instructions to be executed or will hold data to be 
manipulated. By separating RAM into these two categories, a number of interesting 
things start to happen. Instructions are read from the instruction bus and data is read 
and written from the data bus. The actual RAM at the ends of these buses is now 
categorized by function. We have IRAM for RAM that holds instructions to be executed 
and we have DRAM for RAM that holds data. 


We can catch a badly behaving application should it try and write into the instruction 
area of RAM. Since this bus is considered (for the most part) read only, the hardware 
can detect and trap invalid access. 


A second benefit of having two buses is that during the execution of an instruction, the 
next instruction can be started to be read without impacting access to any data needing 
to be accessed by the current instruction as that access will be happening over the 
database. Effectively this allows us to perform certain operations in parallel and allows 
us to perceive an increase in performance. 


Reading and writing registers 
We can the value of a peripheral register using the macro READ PERI_REG(name). This 
is defined in <soc/soc.h>. 


- REG _WRITE 
- REG_READ 

- REG _GET_BIT 

- REG_SET BIT 

- REG_CLR BIT 

- REG_SET BITS 

- REG _GET FIELD 
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REG_SET_FIELD 
VALUE_GET_FIELD 
VALUE_GET_FIELD2 
VALUE_SET_FIELD 
VALUE_SET_FIELD2 
FIELD_TO VALUE 
FIELD_TO_VALUE2 
READ_PERI_REG 
WRITE_PERI_REG 
CLEAR_PERI_REG_MASK 
SET_PERI_REG_MASK 
GET_PERI_REG_MASK 
GET_PERI_REG_BITS 
SET_PERI_REG_BITS 
GET_PERI_REG_BITS2 


Pads and multiplexing 
A pad is an externalized input or output on the ESP32 device. The ESP32 has a total of 
40 pads but only a subset of them are exposed. Within the ESP32 there is a logical 
component called the "Io mux". This is an "Input/Output Multiplexer". In English 
imagine this as a logical "switch board" with some fixed number of actual telephones 
attached to it. When caller wishes to communicate with a telephone, it has to pass 
through the to mux which decides which physical telephone to pass the call to. This 
means that there is a separation between logical "calls" and physical "phones". 


Pads 0-39 can be input 
Pads 0-33 can be output 



































GPIO | Pad Name Function 1 Function 2 Function 3 | Function 4 Function 5 Function 6 
0 GPIOO GPIOO CLK_OUT1 GPIOO 

1 U0TXD U0TXD CLK_OUT3 GPIO1 

2 GPIO2 GPIO2 HSPIWP GPIO2 HS2_DATAO | SD _DDATAO 

3 U0ORXD U0ORXD CLK_OUT2 GPIO3 

4 GPIO4 GPIO4 HSPIHD GPIO4 HS2_DATA1 /|SD_DATA1 

5 GPIOS GPIOS VSPICSO GPIOS HS1_DATA6 
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6 SD_CLK SD_CLK SPICLK GPIO6 HS1_CLK UICTS 
7 SD_DATA_0 SD_DATA_0 |SPIQ GPIO7 HS1_DATAO |U2RTS 
8 SD_DATA_1 SD_DATA_1_ |SPID GPIO8 HS1_DATAL |U2CTS 
9 SD_DATA 2 SD_DATA_2 | SPIHD GPIO9 HS1_DATA2 |UIRXD 
10. |SD_DATA 3 SD_DATA_3_ | SPIWP GPIO10 HS1_DATA3 | UITXD 
11 |SD_CMD SD_CMD SPICSO GPIOI1 HS1_CMD _|UIRTS 

12. | MTDI MTDI HSPIQ GPIO12 HS2_DATA2 |SD_DATA2 
13. |MTCK MTCK HSPID GPIO13 HS2_DATA3_ | SD_DATA3 
14. |MTMS MTMS HSPICLK GPIO14 HS2_CLK SD_CLK 
15 |MTDO MTDO HSPICSO GPIOIS5 HS2_CMD SD_CMD 
16 | GPIO16 GPIO16 GPIO16 HS1_DATA4 |U2RXD 
17. |GPIO17 GPIO17 GPIOI7 HS1_DATAS |U2TXD 
18 | GPIOI8 GPIO18 VSPICLK GPIO18 HS1_DATA7 

19 | GPIO19 GPIO19 VSPIQ GPIO19 UOCTS 

20 | GPIO20 GPIO20 GPIO20 

21. | GPIO21 GPIO21 VSPIHD GPIO21 

22 =| GPIO22 GPIO22 VSPIHD GPIO22 UORTS 

23 | GPIO23 GPIO23 VSPID GPIO23 HS1_ STROBE 

24 

25 | GPIO25 GPIO25 GPIO25 

26 | GPIO26 GPIO26 GPI026 

27. | GPIO27 GPIO27 GP1027 

28 

29 

30 

31 

32. |32K_XP GPIO32 GPIO32 

33. |32K_XN GPIO33 GPIO33 

34. | VDET_1 GPIO34 GPIO34 

35. | VDET_2 GPIO35 GPIO35 

36 |SENSOR_VP | GPIO36 GPI036 

37. |SENSOR_CAPP | GPIO37 GPIO37 

38 |SENSOR_CAPN | GPIO38 GPIO38 

39 |SENSOR_VN _ |GPIO39 GPIO39 





























Now let us think of the "things" that wish to read and write from these pad pins. Some 
of them need to be really fast while others can afford to be slower. For the fast ones, 
we say that these need direct I/O. Examples of fast components include Ethernet, 
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SDIO, SPI, JTAG and UART. The other ones we say are GPIO based and can be used 
by slower functions. Examples of these include I2C, 12S, PWM, LEDC and others. 


Schematically, this might look as follows: 

















Direct 
1/0 
Digital 
10 MUX | <q 
a Pads 
40 
GPIOs — 





What this means is that input/output from the digital pads is governed directly by the 
l1O_MUX controller. Each of the 40 digital pads can be thought of as having a control 
register that says "For a given pad, is this pad connected to GPIO or is it connected to a 
Direct I/O device and, if a direct I/O device ... which one?". 


Now let us add another twist. There is the concept of a "signal". Think of a signal as 
being either output from an internal component or input from an internal component. 
We can map a Signal to a GPIO for input or output. This effectively allows us to matrix 
map anything to anything. In the following diagram, we show this component. 


256 GPIO 
Signals = —_ Matrix —_—> lO_MUX 


To say that a signal will appear on a particular GPIO, we execute the following logic: 








PIN FUNC SELECT (GPIO PIN MUX _REG[gpioNum], PIN _FUNC_GPIO); 
gpio_set_direction(gpioNum, GPIO MODE OUTPUT) ; 
gpio_matrix out(gpioNum, signal, 0, 0); 

















What we do is say that a particular pad (PIN) is going to be used for GPIO which means 
that its data will come from a signal as opposed to direct I/O. Then we say that a 
particular signal is mapped to a GPIO. 


See also: 


Error: Reference source not found 
gpio_matrix_out 
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gpio_set_direction 


Register based GPIO 

There are 34 usable GPIO pins on the ESP32. We should also remember that there 
are 40 pads on an ESP32. Some of the GPIOs are in the 0-31 pad range and some in 
the 32-39 pad range. Since the ESP32 is a 32bit processor, this means that a single 
register can only hold 32 bits of information. As such, we have pairs of registers for 
working with GPIO functions. The first in the pair corresponds to GPIOs on pads 0-31 
and the second on pads 32-39. 


When working with GPIO, there are registers that we can use as follows: 


* Setting a bit in a register causes the output value of the corresponding GPIO to 
be high 


* Setting a bit in a register causes the output value of the corresponding GPIO to 
be low 


Avery useful data structure is defined in soc/gpio_struct.h. The type of the structure is 
called gpio_dev_tand it is exposed via the global GPIO. It contains: 
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bt_select 




















out GPIO 0-31 output 
out_wlts GPIO 0-31 set 
out_wltc GPIO 0-31 clear 
out! GPIO 32-39 output 
outl wlts GPIO 32-39 set 
outl_wltc GPIO 32-39 clear 





sdio_select 





enable 


GPIO 0-31 output enable 





enable_wlts 


GPIO 0-31 output set 





enable_wltc 


GPIO 0-31 output clear 





enablel 


GPIO 32-39 output enable 





enablel_wlts 


GPIO 32-39 output set 





enablel_wltc 


GPIO 32-39 output clear 














strap Boot strapping input data 
in GPIO 0-31 input 

inl GPIO 32-39 input 

status GPIO 0-31 interrupt status 





status_wlts 


GPIO 0-31 interrupt status set 





status_wltc 


GPIO 0-31 interrupt status cleat 





status 1 


GPIO 32-39 interrupt status 





status! wlts 


GPIO 32-39 interrupt status set 





status] _wltc 


GPIO 32-39 interrupt status clear 





acpu_int 


GPIO 0-31 APP CPU interrupt status 





acpu_nmi_ int 


GPIO 0-31 APP CPU non-maskable interrupt status 





pepu_int 


GPIO 0-31 PRO CPU interrupt status 





pepu_nmi_int 


GPIO 0-31 PRO CPU non-maskable interrupt status 





cpusdio_int 





acpu_intl 





acpu_nmi_ intl 





pepu_intl 





pepu_nmi_intl 





cpusdio_ intl 





pin] 





cali_conf 





cali_data 





func_in_sel_cfg[] 
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func_out_sel_cfg 





See also: 


GPIOs 


Strapping pins 

When an ESP32 is powered on, we may wish to control/configure how it boots. To 
achieve this, a set of pins are defined that are read for the very short time that is 
considered the bootstrap time. For the sake of discussion, we should image this as the 
instantaneous time at which the device is powered up. 


The values of these pins are "remembered" and available in the ESP32 register called 
GPIO STRAPPING. The boot-loader will examine these values and act accordingly. We 
can also read this register later to see what values were in effect at boot time. 


The pins have prescribed meanings in the ESP32 architecture: 


Boot mode source 
We can boot from flash memory for normal operation or we can boot to read a new 
program into flash memory for loading an application. 


* cGproo = 1 — Boot from flash. 
¢ cproo = 0 — Boot for loading a new program. 


The floating state is 1 and hence will boot from flash. 


Debugging on UOTXO at boot 

When the ESP32 boot, it can write debugging information out through UARTO and its 
TX pin. This is useful during development but if we want to use this UART in our 
solutions, this diagnostic information will be treated as data over the UART and may 
interfere or confuse any devices attached. We can disable diagnostics from the UART 
by setting a strapping pin value: 


* mTpo = 1 — Use UARTO for debugging (default). 





¢ mtTpo = 0—Do not use UARTO for debugging. 
The floating state is 1 and hence will use UARTO for debugging. 
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Timing of SDIO slave 
A couple of pins are used to configure the SDIO slave interfacing. 


Boot-loader 

The booting mechanism of the ESP32 examines the settings of the "strapping" pins and 
based on their configuration we got into SPI boot mode or UART download mode or 
some other mode that isn't specified. In normal boot mode we examine address 0x1000 
for the image of a software boot-loader. The standard software boot-loader reads the 
partition table to find the "app" image to give control to. 


If we look at an example run of the esptool.py tool, we find that it loads the following: 


bootloader.bin 0x1000 
app.bin 0x10000 
partitions.bin 0x4000 


The in-built ROM in the ESP32 looks in flash address space at 0x1000 and expects to 
find a mapping table. This table lists a set of "segments". Each segment consists of: 


¢ Offset from start of flash area (0x1000) of where the segment starts. 
¢ Length in bytes of the segment. 


¢ Location in ESP32 processor address space where the segment should be 
copied. 


For example, if we run esptool.py --chip image info bootloader.bin We will find: 


esptool.py v2.0-dev 
Image version: 1 
Entry point: 40098200 
4 segments 











Segment 1: len 0x00000 load O0x3ffc0000 file offs 0x00000018 
Segment 2: len 0x00a08 load O0x3ffc0000 file offs 0x00000020 
Segment 3: len 0x01068 load 0x40078000 file offs 0x00000a30 
Segment 4: len 0x00378 load 0x40098000 file offs 0x00001aa0 


Checksum: 92 (valid) 


We can also run xtensa-esp32-elf-objdump -h bootloader.elf! 








Idx Name Size VMA LMA File off Algn 
O .iraml.text 00000378 40098000 40098000 00001b24 2**2 
1 .dram0.bss 00000000 3ffc0000 3£ffc0000 O0000abc 2**0 
2 .dram0.data 00000000 3ffc0000 3£ffc0000 O00000b4 2**0 
3 .dram0.rodata 00000a08 3ffc0000 3£ffc0000 O00000b4 2%**2 
4 .iram_pool 1.text 00001065 40078000 40078000 O0000abc 2**2 
5 .debug frame 00000230 00000000 00000000 O0001le9c 2**2 
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6 .debug_info 00002a37 00000000 00000000 000020cc 2**0 
7 .debug_abbrev 000008fc 00000000 00000000 00004b03 2**0 
8 .debug_loc 00000cac 00000000 00000000 O00053ff 2**0 
9 .debug_aranges 00000118 00000000 00000000 O000060ab 2**0 
10 .debug_ranges 00000110 00000000 00000000 000061c3 2**0 
11 .debug_line 000016a7 00000000 00000000 000062d3 2**0 
12 .debug_str 00000d36 00000000 00000000 0000797a 2**0 
13 .comment 00000022 00000000 00000000 O000086b0 2**0 
14 .xtensa.info 00000038 00000000 00000000 000086d2 2**0 
















































































As a further example, here is an image _ info listing of an application 


esptool.py v2.0-dev 
Image version: 1 










































































Entry point: 40080868 

8 segments 

Segment 1: len 0x0ffe8 load 0x00000000 file offs 0x00000018 

Segment 2: len 0x049b0 load 0x3f£400010 file offs 0x00010008 = .flash.rodata 
Segment 3: len 0x0laa8 load Ox3ffbf2c0 file offs 0x000149c0 = .dram0.data 
Segment 4: len 0x00400 load 0x40080000 file offs 0x00016470 | .iram0.vectors 
Segment 5: len 0x163b0 load 0x40080400 file offs 0x00016878 | .iram0.text 
Segment 6: len 0x00000 load 0x400c0000 file offs 0x0002cc30 > .rtc.test 
Segment 7: len 0x033d0 load 0x00000000 file offs 0x0002cc38 

Segment 8: len 0x2965c load 0x400d0018 file offs 0x00030010 = .flash.text 
Checksum: c5 (valid) 

and an edited version of the objdump: 

Idx Name Size VMA LMA File off Algn 













































































0 .iram0.vectors 00000400 40080000 40080000 00006538 2**2 
1 .iram0.text 000163ae 40080400 40080400 00006938 2**2 
2 .dram0.bss O000f2cO 3£ffb0000 3£ffb0000 00004a90 2%**3 
3 .dram0.data 0000laa8 3ffbf2cO 3£ffbf2cO0 00004a90 2**4 
4 .flash.rodata 000049b0 3400010 3£400010 000000e0 2**4 
5 .flash.text 00029659 400d0018 400d0018 O0001cce8 2**2 
6 .rtc.text 00000000 400c0000 400c0000 00046341 2**0 
7 .debug_ frame 00005590 00000000 00000000 00046344 2**2 
8 .debug_info 0O0070fbb 00000000 00000000 0004b8d4 2**0 
9 .debug_abbrev 000101a2 00000000 00000000 O00bc88f 2**0 
10 .debug_loc 000231lce 00000000 00000000 O000cca31 2**0 
11 .debug_aranges 000024c0 00000000 00000000 O00efc00 2**3 
12 .debug_ ranges 00002a20 00000000 00000000 O00f20c0O 2**3 
13 .debug line 0002d918 00000000 00000000 O00f4ae0 2**0 
14 .debug_ str 00012101 00000000 00000000 001223f8 2**0 
15 .comment 00000062 00000000 00000000 001344f9 2**0 
16 .xtensa.info 00000038 00000000 00000000 0013455b 2**0 
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Partition Table 
As of the time of writing, the partition table is not "baked" and should be ignored 


pending further information being published. 


Within flash memory, a concept called the "partition table" is written. This exists at 
memory location 0x4000. Each row in the table is composed of five items: 


The default single factory app with no OTA is: 


name/label 
type 

subtype 
offset in flash 


size 





















































Name Type Subtype Offset Size 
factory app factory 0x 10000 1M 
rfdata data rf 0x110000 256K 
wifidata data wifl 0x 150000 256K 
For the two OTA definitions, we have: 

Name Type Subtype Offset Size 
factory app factory 0x 10000 1M 
ota_0 app ota_0 1M 
ota_1 app ota_1 1M 
rfdata data rf 256K 
wifidata data wifi 256K 
otadata data ota 256K 




















The type field in the table can be: 











Value Description 
0x00 app 
0x01 data 





0x00-0x3F | reserved 








Ox40-OxFE | user specified 





OxFF 





reserved 











The sub-type field can be: 
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When type is app: 





Value Description 





0x00 factory 





0x10 ota_0 





0x11 otal 








Ox1F ota_15 





0x20 test 














When type is data: 














Value Description 
0x00 ota 

0x01 rf 

0x02 wifi 














The offset size is optional. Blank offsets will be placed contiguously after the previous 
data. Offsets are 64K aligned. 


A tool called "gen esp32part.py" is available as part of the tooling to build binary 


representations of the table. We can build a binary table from a comma separated 
value file using: 


$ gen_esp32part.py -verify input _partitions.csv binary partitions.bin 


We can convert a binary file back to a CSV using: 


$ gen_esp32part.py --verify binary partitions.bin input _partitions.csv 


and we can list the content of a binary file using: 


$ gen_esp32part.py binary partitions.bin 


A binary table is determined to be such because the first two bytes are 0xAA 0x50. 
See also: 


Partition API 
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Power modes 

The ESP32 can operate in different power modes. The distinguishing feature is how 
much current is consumed. Ideally we want the ESP32 to consume as little power as 
possible and the trade off on this is the amount of function that can be performed 
against current consumption. The items that affect current consumption includes 


¢ Radio on or off 
* CPUs on or off 
¢ RAM being maintained 
The distinct modes of operation have names associated with them: 


¢ Active mode — This is the normal operational mode. The radio is on and it can 
both transmit and receive. 


¢ Modem-sleep mode — In this mode the radio is powered off but other functions 
remain enabled. Radio is the biggest consumer of power. 


¢ Light-sleep mode — The CPUs are paused however the RTC and ULP-co- 
processor remain operational. A variety of events can wake up the processor 
including timers or external interrupts. 


¢ Deep-sleep mode — Only the RTC has power. 


¢ Hibernation mode — Only one timer or an external RTC interrupt can wake us up. 


Bootloader 

When a device is powered up, control is given in a raw state to an area of code called 
the "bootloader". The responsibility of a bootloader is to bring the system up to a usable 
state and then load and give control to a user written application. The bootloader for 
ESP32 is supplied as the bootloader component within the ESP-IDF environment. 
Studying the bootloader provides us great incite into how the ESP32 operates. 


Control starts at call start cpu0 


call_start_cpu0 { 
reset CPU caches; 
call bootloader main () 


} 
The bootloader main() is responsible for much of the work: 


bootloader main() { 
// Load the bootloader header data from SPI address 0x1000 
call esp image _load_header(); 





// Load the partition table. 
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call load _patition table(); 
} 


Peripherals 


Remote Control Peripheral - RMT 

The primary purpose of this component of the ESP32 is to generate pulses sent via an 
infrared LED. When you point your TV remote control at your TV and press a button, an 
infrared LED at the front sends a sequence of pulses that are received by the TV and 
decoded. Since an infrared LED can be either "on" or "off" at any given time, the signal 
is encoded in the duration that the LED is either on or off. Whether the LED is on or off 
and for how long we call a data item. To use the RMT component, we build an array of 
data items and pass those to the RMT with the intent that it will then own the generation 
of the correct signals. 


A data item is composed of a 16 bit value. 





level [15] period [14:0] 











The level bit is either 1 or 0 describing the output signal while the period (15 bits in 
length) is the duration in clock ticks. 15 bits give us a range from 1-32767. A value of 0 
for the period is used as an end marker. The normal maximum number of data item 
records is 128. 


The RMT has 8 distinct channels with each channel having 128 16 bit records. Should 
we wish to send more than 128 records, we can extend a channel to use the channel 
data of subsequent adjacent channels. For example, if we are using only channel 0 
then the data available for it can be that of channel 0, channel 1 up to channel 7 giving 
us a total of 1024 value records (1024 data items or 2048 bytes). The number of 
channels of data used by a specific channel is set in the register RMT MEM OWNER_CHn. 














There is also an interesting mechanism that involves the buffer for a channel wrapping 
around. Imagine that we have a default buffer size of 128 * 16bit records. If we need to 
send more than 128 records, we can pre-load a buffer with our first 128 values and set 
the RMT transmitting. When it has transmitted the first 128 values, it will generate an 
interrupt that can be used to re-fill the buffer with the new values and progress will 
continue. 


The RAM for these blocks starts at RMT base address + 0x800. 


Assuming each channel uses just its own block, the channels start at: 
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Channel Address 

0 RMT base address + 0x800 

1 RMT base address + 0x800 + 0x100 
2 RMT base address + 0x800 + 0x200 
3 RMT base address + 0x800 + 0x300 
4 RMT base address + 0x800 + 0x400 
5 RMT base address + 0x800 + 0x500 
6 RMT base address + 0x800 + 0x600 
7 RMT base address + 0x800 + 0x700 











Each channel has two control registers associated with it called RMT cHncONFO REG and 
RMT CHnCONF1 REG. 


Register —- RMT_CHnCONFO_REG 




































































Name Bits Field Description 
reserved [31 clk_en Reserved. Set to 0. 
RMT_MEM PD [30 mem_pd Power down memory. 
° 0— memory is powered up 
° 1 — memory is powered down 
RMT CARRIER OUT LV CHn | [29 carrier out_lv Carrier present on: 
° 0 — transmit on high 
° 1 — transmit on low 
RMT CARRIER_EN CHn 28 carrier en Is carrier signal enabled? 
° 0 — disabled 
° 1- enabled 
RMT MEM SIZE CHn 27:24] |mem_size Memory blocks allocated to channel. 4bits. (0x01) 
RMT_IDLE_THRESH_CHn 23:8] idle _thres Clock cycles of no change indicates an end of reception in receive 
mode. (0x1000) 
RMT _DIV_CNT_CHn 7:0] div_cnt Divider for channel clock. (0x02) 





Register —- RMT_CHnCONF1_REG 
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Name Bits Field Description 


















































reserved [31:20] reserved20 Reserved. Set to 0. 
RMT_IDLE_ OUT _EN CHn [19] idle_out_en Output enable. (0) 
RMT_IDLE_OUT_LV_CHn [18] idle_out_lv Output signal in idle state. (0) 
RMT_REF_ ALWAYS ON_CHn [17] ref_always_on Selection of channel base clock: 

° 0 —clk_ref. 

° 1 —clk_apb. 
RMT_REF_CNF_RST_CHn 16] ref_cnf_rst Reset the clock divider. (0) 
RMT _RX_FILTER_THRES_CHn 15:8] rx_filter_thres Threshold for of pulse width in receive mode. (0x0f) 
RMT _RX_FILTER_EN_CHn 7 rx_filter_en Enable receive filter. (0) 
RMT_TX_CONTI_MODE_CHn 6 tx_conti_mode Enable repeating transmission. 

7 0 — Go idle at end of transmission. 

° 1 — Repeat at end of transmission. 
RMT MEM OWNER _CHn 5 mem_owner Block used for receive or transmit? 

° 0 — RAM used for transmission. 


° 1— RAM used for reception. 




















reserved 4 apb_mem_rst Reserved. Set to 0. 
RMT_MEM RD_RST_CHn 3 mem_rd_rst Reset read ram for transmitter access. (0) 
RMT_MEM WR_RST_CHn 2 mem_wr_rst Reset write ram for receiver access. (0) 
RMT_RX_EN_CHn 1 rX_en Enable receiving on channel. 

1 — Start receiving. (0) 
RMT_TX_START_CHn 0 tx_start Start sending on channel. 




















1 — Start transmitting. (0) 





Let us imagine we want to send 8 bits of square wave through channel 0. This means 
we will want 17 records (one for each value transition and a terminator). We will then 
want to set RMT _CHOCONFO_ REG to 


¢ RMT_MEM_PD = 0 (Power up memory) 
¢ RMT_CARRIER_EN_CHO = 0 (carrier disabled) 
¢ RMT_MEM_SIZE_CHO = 1 (1 memory block) 
¢ RMT_DIV_CNT_CHO = 1 (divider for clock) 
We will also want to set RMT_CHOCONF1_REG to: 
¢ RMT_IDLE_OUT_EN_CHO = 1 (Output enable) 
¢ RMT_IDLE_OUT_LV_CHO = 0 (0 in idle state) 
¢ RMT_REF_ALWAYS ON _CHO = 0 (channel base clock) 
¢ RMT_MEM_OWNER_CHO = 0 (used for transmission) 
¢ RMT_MEM_RD_RST_CHO = 1 (Reset read ram) 
¢ RMT_RX_EN_CHO = 0 (Enable transmit on channel) 
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¢ RMT_TX_START_CHO = 1 (Start transmitting) 


Within the header file called "soc/rmt_struct.h" we have a global variable defined 
called rutvem that contains definitions of the data buffers. 





There is also a variable called RMT that contains the 


The signal mapping for GPIQOs is: 












































Function Signal Constant 

rmt_sig out0 /87 RMT SIG OUTO IDX 
rmt_sig outl |88 RMT SIG OUTI IDX 
rmt_sig out2 /89 RMT SIG OUT2_ IDX 
rmt_sig out3 |90 RMT SIG OUT3_ IDX 
rmmt_sig out4 /91 RMT SIG OUT4 IDX 
rmt_sig outS |92 RMT SIG OUTS _IDX 
rmmt_sig out6 | 93 RMT SIG OUT6 IDX 
rmt_sig out7 |94 RMT SIG OUT7_ IDX 





To say that a signal will appear on a particular GPIO, we execute the following logic: 


include "soc/gpio_sig_map.h" 


int gpioNum = 17; 

PIN FUNC_SELECT(GPIO_PIN MUX _REG[gpioNum], PIN _FUNC_GPIO); 
gpio_set_direction(gpioNum, GPIO MODE OUTPUT) ; 

gpio_ matrix out(gpioNum, RMT SIG OUTO IDX, 0, 0); 




















SPI 

The header file called "soc/spi_struct.h" provides a data type called "spi_dev_t" that 
is amemory map into the registers that control SPI. There are four instances of this 
structure, one for each of the hardware SPIs available on an ESP32. These are called 
SPIO, SPI1, SPI2 and spr3. spro Is reserved for internal use and should be ignored. 


If one looks there, you will find a bewilderingly large number of settings. Poking those 
values correctly to achieve SPI is not a trivial matter and documentation on those 
features is still a while away. 


See also: 


Error: Reference source not found 
The Arduino Hardware Abstraction Layer SPI 


PID Controller 
| have no idea what this is. 
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UART 
Read the UART status register? 


READ_PERI_REG(UART_INT_ST_REG(??)) 
UART_FRM_ERR_INT_ENA---? 

UART_RXFIFO_TOUT_INT_ENA — Timeout interrupt enable 
UART_RXFIFO_FULL_INT_ENA — RX FIFO length is > than threshold 


UART_GET_RXFIFO_CNT —> #define to 


#define UART_GET_RXFIFO_CNT(i) 
GET_PERI_REG_BITS2(UART_STATUS_REG(i) , UART_RXFIFO_CNT_V, 
UART_RXFIFO_CNT_S) 


Number of bytes in RX queue 


UART_GET_RXFIFO_RD_BYTE — #define to 


#define UART_GET_RXFIFO_RD_BYTE(i) 
GET_PERI_REG_BITS2(UART_FIFO_REG(i) , UART_RXFIFO_RD_BYTE_V, 
UART_RXFIFO_RD_BYTE_S) 


Read a byte from the RX queue 


Electronics 


Logic Level Shifting 

We have already read that the ESP32 GPIO pins are 3.3V tolerant. This means that the 
maximum input voltage must be 3.3V. If you go higher than that, you are at risk for 
frying your device. But what if we have a peripheral device that outputs a 5V signal? 
Conversely, the maximum output voltage on a Pi GPIO is 3.3V. If we feed that as input 
to a peripheral that is expecting a 5V input, there is no assurance that it will detect the 
signal correctly. Fortunately there is a solution in a circuit called a logic level shifter. 
This circuit can convert a 3.3V signal to a 5V signal and can also convert a 5V signal to 
a 3.3V signal. 


The module takes as input +ve and ground of the high level and +ve and ground of the 
low level and provides bi-directional switching. 
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If you don't have access to such logic level circuits, an alternative solution is to create a 
voltage divider. This will protect 3V Pi inputs from over voltage from a 5V source. This 
is a simple circuit made with two resistors. A higher voltage is provided to input than 
output and using a correct combination of resistors, the input voltage is proportionally 
scaled to the output voltage. 


Vin 
re Vout 


There is an equation available to us: 
_Vi»xXR2 
ou R1+R2 


As an example of a solution to this equation, if Vin is 5V and we want Vou to be 3.3V and 
choose 1KQ for R2 then ... 


3.3<__1000 


=———_ X5 
R1+1000 


Which evaluates to R1 having a value of 515Q. We can use a higher value for R1 but 
not lower. 


Expressing the equation in a different order we have: 
(Vin —V ou) XR 2 


R1= 
V 





out 


See also: 


¢ Sparkfun — Bi-Directional Logic Level Converter Hookup Guide 








¢ Wikipedia — Voltage divider 
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Projects 


JerryScript library for ESP32 

JerryScript is JavaScript for embedded devices including the ESP32. However, just like 
JavaScript on other platforms, it provides only the language. What this means is that 
there are no libraries of higher functions supplied by default. Projects such as loT.js 
would be perfect, but it appears that their requirements and dependencies are currently 
too function rich for a trivial port to ESP32. 


As a result of that, we now look to see if we can't do something more pragmatic. We 
will borrow wherever possible from the semantics and descriptions of Node.js which is 
the industry de-facto standard. 

The "require" capability 

The concept is that we can load "modules" by name. A module is the dynamic sourcing 
of function which returns a JavaScript object that services that function. 

Generically, we will code: 


let myVar = require("<Module Name>") ; 


Our implementation will be general enough to return built-in modules as well as external 
modules. 


See also: 


JerryScript 


API Reference 

Now we have a mini reference to the syntax of many of the ESP32 exposed APIs as 
well as related libraries. Do not use this reference exclusively. Please also refer to the 
published Espressif SDK Programming Guide and other sources of literature. Part of 
the purpose of recreating this quick listing is so that it can be cross referenced in the 
examples as well as serving as a place where notes about using an API in the context 
of an ESP32 can be captured. 


Some acronyms and other names are used in the naming of APIs and may need some 
explanation to fully appreciate them: 


¢ dhcpc — DHCP client 
¢ dhcps — DHCP server 
¢ softap — Access point implemented in software 


* wps — WiFi Protected Setup 
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¢ sntp — Simple Network Time Protocol 
¢« mdns — Multicast Domain Name System 
¢ uart — Universal asynchronous receiver/transmitter 


* pwm — Pulse width modulation 


Configuration, status and operational retrieval 

There are certain APIs available to us that can be used to interrogate the operation of 
an ESP32 and some of its distinct parts and components. The detailed documentation 
for these APIs are found in the corresponding links ... but here we list their existence 
and brief description of what they provide: 


system_get_time - Get the system time measured in microseconds since last device start-up. 
esp_get_free_heap_size - Get the amount of free heap size. 

esp_wifi_scan_get_ap_records - Retrieve the access points found in a previous scan. 
esp_wifi_scan_get_ap_num - Retrieve the count of found access points from a previous scan. 
esp_wifi_get_auto_connect - Determine whether or not auto connect at boot is enabled. 
esp_wifi_get_bandwidth - Get the current bandwidth setting. 

esp_wifi_get_channel - Get the current channel. 

esp_wifi_get_config - Retrieve the current connection information associated with the specified WiFi interface. 
esp_wifi_get_country - Retrieve the currently configured WiFi country. 

esp_wifi_get_mac - Retrieve the current MAC address for the interface. 

esp_wifi_get_mode - Get the WiFi operating mode. 

esp_wifi_get_promiscuous 

esp_wifi_get_protocol - Get the 802.11 protocol (b/g/n). 

esp_wifi_get_ps - Get the power save type. 

esp_wifi_get_station_list - Get the list of stations connected to ESP32 when it is behaving as an access point. 
tcpip_adapter_get_ip_info 

tcpip_adapter_get_sta_list 

tcpip_adapter_get_wifi_if 


Arduino Mapping 

The Arduino APIs are a library of functions available within the Arduino ecosystem. 
There may be times when we want to port an Arduino library to the ESP-IDF 
environment. This section lists some of the more common Arduino APIs and how they 
can be mapped to the ESP-IDF. 


bitRead 


bitRead(x, n) 


The equivalent is: 


(x & l<<n) != 0 
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bitWrite 


bitWrite(x, n, b) 


x = (x & (~(1<<n)) | (b << n)) 


delay 


delay (ms) 


The equivalent in ESP-IDF is: 


vTaskDelay(ms/portTICK PERIOD MS) 





See also: 


vTaskDelay 
Arduino — delay() 


digitalWrite 


digitalWrite(pin, value) 


The equivalent in ESP-IDF is: 


gpio_set_level() 


Parameter mappings: 




















HIGH 1 
LOW 0 
See also: 


gpio_set_level 
Arduino — digitalWrite() 





pinMode 


pinMode (pin, mode) 


The equivalent in ESP-IDF is: 
gpio_set direction () 


Parameter mappings: 





mode=INPUT GPIO_MODE_ INPUT 





mode=OUTPUT GPIO_MODE OUTPUT 








mode=INPUT_PULLUP GPIO_MODE_ INPUT with an additional call to gpio_set_pull_mode(). 
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See also: 


gpio_set_direction 


Arduino — pinMode() 


SPI.begin 


SPI .begin () 


The equivalent in ESP-IDF is: 


spi_bus_initialize(); 
spi_bus_add_device(); 


See also: 


spi_bus_add_device 
spi_bus_ initialize 
Arduino — SPI.begin() 





SPI.setBitOrder 


SPI.setBitOrder 
The equivalent in ESP-IDF is: 
spi_bus_add_device() 


and setting the flags properties. The default is MSB but within the flags we can specify 
LSB for either or both of the RX or TX. 


See also: 


spi_bus_add_device 
Arduino — SPL.setBitOrder() 





SPI.setClockDivider 


SPI.setClockDivider () 

The equivalent in ESP-IDF is: 
spi_bus_ add _device() 

and setting the clock speed in Hz. 
See also: 


spi_bus_add_device 
Arduino — SPI.setClockDivider() 





SPI.setDataMode 


SPI.setDataMode () 
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The equivalent in ESP-IDF is: 
spi_bus_add_device() 

and setting the mode property of the structure. 
See also: 


spi_bus_add_device 
Arduino — SPI.setDataMode() 





SPlI.transfer 
SPl.transfer (val) 
SPlI.transfer (buffer, size) 


The equivalent in ESP-IDF is: 


spi_ device transmit () 





See also: 


spi_device_transmit 
Arduino — SPL.transfer() 





Wire.begin 
Initialize the I2C interface. 


Wire.begin () 
Wire.begin (address) 


The equivalent ESP-IDF is 


i2c_cmd_handle _t cmd = i2c_ cmd_link create(); 
i2c_master start(cmd); 





i2c_master write byte(cmd, (address << 1) | I2C_ MASTER WRITE 


Wire.beginTransmission 
Wire.beginTransmission (address) 


The equivalent ESP-IDF is: 


i2c_cmd_handle t cmd = i2c_ cmd_link create(); 
i2c_master start(cmd); 


i2c_master write byte(cmd, (address << 1) | I2C_ MASTER WRITE 





Wire.endTransmission 


Wire.endTransmission () 


The equivalent ESP-IDF is: 


i2c_master stop(cmd) ; 
i2c_ master cmd_begin(0, cmd, 0); 
i2c_cmd_link delete (cmd) ; 





= 














= 





’ 


, 


1 /* expect ack */); 


1 /* expect ack */); 
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Wire.read 
Wire. read () 


The equivalent ESP-IDF is: 


i2c_master read(cmd, data, length, ack) 
i2c_master read _byte(cmd, data, ack) 


Wire.requestFrom 
Wire.requestFrom(address, quantity) 


Wire.write 
Wire.write (string) 
Wire.write(data, length) 


The equivalent ESP-IDF is: 


i2c_ master write(cmd, data, length, 1); 


FreeRTOS API reference 
See also: 


Using FreeRTOS 


portENABLE_INTERRUPTS 
Enable interrupts and context switching. 


portDISABLE_INTERRUPTS 
Disable interrupts and context switching. 


xPortGetCorelD 
This is a macro that returns the current core ID on which we are running. 


uint32 xPortGetCorelID() 


Since the ESP32 has two cores, the result will either only ever be 0 or 1. 


pvPortMalloc 
Allocate storage. 


void *pvPortMalloc(size t size) 


See also: 


malloc 


pvPortFree 
Release storage. 
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void vPortFree(void *data) 


xEventGroupClearBits 
Clear one or more bits in an event group. 





EventBits _t xEventGroupClearBits ( 
EventGroupHandle t eventGroup, 








const EventBits t bitsToClear) 

* eventGroup — The event group that contains the bits to be cleared. 

* bitsToClear — The set of bits to be cleared within the event group. 
Includes: 

¢ #include <freertos/FreeRTOS.h> 

¢ #include <freertos/event_groups.h> 


See also: 


Blocking and synchronization within RTOS 


xEventGroupCreate 
Create a new FreeRTOS event group. 








EventGroupHandle t xEventGroupCreate () 
Includes: 

¢ #include <freertos/FreeRTOS.h> 

¢ #include <freertos/event_groups.h> 


See also: 


Blocking and synchronization within RTOS 


xEventGroupSetBits 
Set one or more bits in an event group. 





EventBits t xEventGroupSetBits ( 





EventGroupHandle t eventGroup, 








const EventBits_ t bitsToSet) 
* eventGroup — The event group that contains the bits to be set. 
* bitsToSet — The set of bits to be set within the event group. This is a bit mask. 


Includes: 
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¢ #include <freertos/FreeRTOS.h> 
¢ #include <freertos/event_groups.h> 


See also: 


Blocking and synchronization within RTOS 


xEventGroupWaitBits 
Block waiting for one or more "bits" to become set. 





EventBits t xEventGroupWaitBits ( 
const EventGroupHandle t eventGroup, 
const EventBits_t bitsToWaitFor, 








const BaseType t clearOnExit, 








const BaseType t waitForAllBits, 
TickType t ticksToWait) 


Calling this function can cause the caller to block until bits are set or a timeout is met. 
Bits can be set through xEventGroupSetBits (). 





* eventGroup — The event group that references the bits to be watched. 


* bitsToWaitFor — The set of bits within the event group that we are waiting upon. 
This is a bit mask. 


* clearOnExit — Should the bits that we are waiting on be cleared automatically 
when set and this method returns? 





* waitForAl1Bits — Should we unblock on the first bit that is set that we are 
watching for or alternatively should we wait on all the bits being set? 


* ticksTowWait — How many ticks should we wait for before returning? This 
provides a timeout (if needed). The RTOS variable "portmax DELAY" can be used 
to specify that we wish to wait indefinitely. 





Includes: 
¢ #include <freertos/FreeRTOS.h> 
¢ #include <freertos/event_groups.h> 


See also: 


xEventGroupSetBits 
Blocking and synchronization within RTOS 


xQueueAddToSet 
Add a queue to the set of queues monitored by this queue set. 
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BaseType t xQueueAddToSet ( 
QueueSetMemberHandle t xQueueOrSemaphore, 
QueueSetHandle t xQueueSet) 











See also: 


xQueueCreateSet 
xQueueRemoveFromSet 
xQueueSelectFromSet 


xQueueCreate 
Create a queue for holding items. 


QueueHandle t xQueueCreate ( 
UBaseType t uxQueueLength, 








UBaseType t uxItemSize) 


This call creates a queue for holding queue items. The maximum number of items that 
the queue can hold is supplied as well as the size of each item in a queue. On return, a 
handle to the new queue is supplied or has a value of NULL on error. 


If the queue is no longer needed, it can be deleted with a call to voueueDelete(). 
* uxQueueLength — The maximum number of items that the queue can contain. 
* uxItemSize — The size in bytes reserved for each element in the queue. 
Includes: 
¢ #include <freertos/FreeRTOS.h> 
¢ #include <freertos/queue.h> 


See also: 


vQueueDelete 
xQueueCreate 


xQueueCreateSet 
Create a queue set. 





QueueSetHandle t xQueueCreateSet( const UBaseType t uxEventQueueLength) 





The uxEventQueueLength must be at least the size of all the queues that will be 
concurrently watched by this queue set. 


See also: 


xQueueAddToSet 
xQueueRemoveFromSet 
xQueueSelectFromSet 
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xQueueCreateStatic 
Create a queue for holding items but allow the application to own the management of 
queue records. 


QueueHandle t xQueueCreateStatic ( 
UBaseType t uxQueueLength, 
UBaseType t uxItemSize, 
uint8 t *queueStorageBuffer, 
StaticQueue t pxQueueBuffer) 











Includes: 
¢ #include <freertos/FreeRTOS.h> 


¢ #include <freertos/queue.h> 


vQueueDelete 
Delete a previously created queue. 





void vQueueDelete (xQueueHandle xQueue) 
Includes: 
¢ #include <freertos/FreeRTOS.h> 
¢ #include <freertos/queue.h> 


See also: 


xQueueCreate 
xQueueCreateStatic 


xQueueGenericReceive 
BaseType t xQueueGenericReceive( QueueHandle t xQueue, void * const pvBuffer, 
TickType t xTicksToWait, const BaseType t xJustPeek) 








uxQueueMessagesWaiting 
Return the count of messages on the queue. 





UBaseType t uxQueueMessagesWaiting (QueueHandle t xQueue) 
The return is the number of messages currently on the queue. 
Includes: 

¢ #include <freertos/FreeRTOS.h> 


¢ #include <freertos/queue.h> 
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xQueueOverwrite 





BaseType t xQueueOverwrite (QueueHandle t xQueue, const coid *pvItemToQueue) 


Includes: 
¢ #include <freertos/FreeRTOS.h> 


¢ #include <freertos/queue.h> 


xQueuePeek 

BasType t_ TYPE xQueuePeek ( 
QueueHandle t xQueue, 
void *pvBuffer, 
TickType t xTicksToWait) 





Includes: 
¢ #include <freertos/FreeRTOS.h> 


¢ #include <freertos/queue.h> 


xQueuePeekFromliSR 


BaseType t xQueuePeekFromISR( QueueHandle t xQueue, void * const pvBuffer) 








xQueueReceive 
Retrieve an item from the head of the queue. 





BaseType t xQueueReceive ( 
QueueHandle t xQueue, 
void *pvBuffer, 
TickType t xTicksToWait) 





The xQueue is the handle to the queue we wish to receive from. Th 


@ pvBuffer iS a 


pointer to storage that will receive the item from the queue. The xTicksTowWait is how 


long we wish to wait for an item to become available assuming the 
Specifying 0 means return immediately while specifying portMAx_Di 
indefinitely. 

















The return is papass if we receive an item or errQUEUE EMPTY IS NO 
Includes: 
¢ #include <freertos/FreeRTOS.h> 


¢ #include <freertos/queue.h> 


queue is empty. 
ELAY means block 





item was retrieved. 
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xQueueReceiveFromliSR 

BaseType t xQueueReceiveFromISR ( 
QueueHandle t xQueue, 
void *pvBuffer, 
BaseType t *pxHigherPriorityTaskWoken 








xQueueRemoveFromSet 

BaseType t xQueueRemoveFromSet ( 
QueueSetMemberHandle t xQueueOrSemaphore, 
QueueSetHandle t xQueueSet) 














xQueueReset 
BaseType t xQueueReset (QueueHandle t xQueue) 





Includes: 
¢ #include <freertos/FreeRTOS.h> 


¢ #include <freertos/queue.h> 


xQueueSelectFromSet 
Watch a queue set for a member becoming ready. 





QueueSetMemberHandle t xQueueSelectFromSet ( 
QueueSetHandle t xQueueSet, 
const TickType t xTicksToWait) 





The return is the handle of the queue which is ready for reading without blocking. 


See also: 


xQueueAddToSet 
xQueueCreateSet 
xQueueRemoveFromSet 


xQueueSelectFromSetFromlSR 
QueueSetMemberHandle t xQueueSelectFromSetFromISR(QueueSetHandle t xQueueSet) 








xQueueSend 
This is a macro for backwards compatibility only. Do not use for new projects. 
BaseType t xQueueSend ( 


QueueHandle t xQueue, 
const void *pvItemToQueue, 
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TickType t xTicksToWait 
i 


xQueueSendFromliSR 
This is a macro for backwards compatibility only. Do not use for new projects. 





BaseType t xQueueSendFromISR ( 
QueueHandle t xQueue, 
const void *pvItemToQueue, 





BaseType t *pxHigherPriorityTaskWoken 
i 


xQueueSendToBack 
Place an item at the end of the queue. 


BaseType t xQueueSendToBack ( 
QueueHandle t xQueue, 
const void * pvItemToQueue, 
TickType t xTicksToWait) 











The xQueue is the reference to the queue into which we are going to place the item. The 
pvItemToQueue Is a pointer to the item we are going to copy into the queue. Note that 
this is indeed a copy and not saved as a reference. The xTicksTowait is how long we 
are prepared to wait if the queue is currently full. Specifying 0 returns immediately while 
portMAX_DELAy blocks indefinitely. 





On return the value papass indicates that the message was queued while 
errQUEUE_FULL indicates that the message was not queued and we timed out waiting for 
space to become available. 














Includes: 
¢ #include <freertos/FreeRTOS.h> 


¢ #include <freertos/queue.h> 


xQueueSendToBackFromISR 
Place an item at the end of the queue. 





BaseType t xQueueSendToBackFromISR ( 
QueueHandle t xQueue, 
const void *pvItemToQueue, 








BaseType t *pxHigherPriorityTaskWoken 
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This function is an ISR safe version of the xQueueSendToBack() function. The xQueue 
is the reference to the queue into which we are going to place the item. The 
pvItemToQueue Is a pointer to the item we are going to copy into the queue. Note that 
this is indeed a copy and not saved as a reference. 


The pxHigherPriorityTaskWoken Is a pointer to a flag that is set on return. If its value is 
pdTRuE then a higher priority task is ready and a context switch is possible. It can be 
NULL to be ignored. 








The return is papass if the item was queued otherwise errQUEUE_ FULL to indicate that the 
queue was full. 











Includes: 
¢ #include <freertos/FreeRTOS.h> 
¢ #include <freertos/queue.h> 


See also: 


xQueueSendToBackFromISR 





xQueueSendToFront 
BaseType t xQueueSendToFront ( 





QueueHandle t xQueue, 

const void * pvItemToQueue, 

TickType t xTicksToWait) 
The xQueue is the reference to the queue into which we are going to place the item. The 
pvItemToQueue Is a pointer to the item we are going to copy into the queue. Note that 
this is indeed a copy and not saved as a reference. The xTicksTowWait is how long we 
are prepared to wait if the queue is currently full. Specifying 0 returns immediately while 
portMAX_DELAy blocks indefinitely. 





On return the value papass indicates that the message was queued while 
errQUEUE_FULL indicates that the message was not queued and we timed out waiting for 
space to become available. 














Includes: 
¢ #include <freertos/FreeRTOS.h> 


¢ #include <freertos/queue.h> 


xQueueSendToFrontFromliSR 
BaseType t xQueueSendToFrontFromISR ( 
QueueHandle t xQueue, 
const void *pviItemToQueue, 
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BaseType t *pxHigherPriorityTaskWoken 


uxQueueSpacesAvailable 
UBaseType t uxQueueSpacesAvailable (QueueHandle t xQueue) 





Includes: 
¢ #include <freertos/FreeRTOS.h> 


¢ #include <freertos/queue.h> 


xRingbufferAddToQueueSetRead 

BaseType t xRingbufferAddToQueueSetRead ( 
RingbufHandle t ringbuf, 
QueueSetHandle t xQueueSet) 





xRingbufferAddToQueueSetWrite 
Add the ring buffer as an indicator item to the queue set. 


BaseType t xRingbufferAddToQueueSetWrite ( 
RingbufHandle t ringbuf, 
QueueSetHandle t xQueueSet) 





Making this call adds the ring buffer to the queue set such that a write to the ring buffer 
will cause a trigger of any queue set being watched. 


See also: 


xQueueCreateSet 
xQueueSelectFromSet 


xRingbufferCreate 
Create a new ring buffer. 


RingbufHandle t xRingbufferCreate ( 
size_t buf_length, 
ringbuf_type t type) 
¢ length — The size in bytes that we wish to allocate for the ring buffer. 


¢ type — The type of ring buffer with respect to how wrapping is to occur. The 
choices are: 


o RINGBUF_TYPE_NOSPLIT 
o RINGBUF_TYPE_ALLOWSPLIT 
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o RINGBUF_TYPE_BYTEBUF 


vRingbufferDelete 
Delete a ring buffer. 


void vRingbufferDelete (RingbufHandle t ringbuf) 


Delete a ring buffer previously created with a call to xRingbufferCreate(). 


xRingbufferGetMaxltemSize 
Get the maximum size of an item that will fit within the remaining space in the ring 
buffer. 


size t xRingbufferGetMaxItemSize (RingbufHandle t ringbuf) 





xRingBufferPrintInfo 
void xRingbufferPrintInfo (RingbufHandle t ringbuf) 


xRingbufferReceive 
Retrieve an item from the ring buffer. 


void *xRingbufferReceive ( 
RingbufHandle t ringbuf, 





size t *item_size, 
TickType t ticks to wait) 


* ringbuf — The ringbuf to receive an item from. 
* item size — The size of the item received. 


* ticks to wait —How long to wait. Specify portmax pbrELay for an indefinite block. 





The return from this call is a pointer to storage that is the next item within the buffer. 
Since items in a ring buffer can be of distinct sizes, the item size variable is populated 
with the size of the data in this returned record instance. We must subsequently call 
vRingbufferReturnItem() to release the storage when we are finished with it. 


xRingbufferReceiveFromlSR 
void *xRingbufferReceiveFromISR ( 
RingbufHandle t ringbuf, 





size t *item_size) 
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xRingbufferReceiveUpTo 
Return data from the ring buffer up to a maximum size. 


void *xRingbufferReceiveUpTo ( 
RingbufHandle t ringbuf, 





size t *item_size, 
TickType t ticks to wait, 
size_t wanted_size) 


xRingbufferReceiveUpToFromiSR 
void *xRingbufferReceiveUpToFromISR ( 
RingbufHandle t ringbuf, 





size t *item_size, 
size_t wanted size) 


xRingbufferRemoveFromQueueSetRead 
BaseType t xRingbufferRemoveFromQueueSetRead ( 
RingbufHandle t ringbuf, 
QueueSetHandle t xQueueSet) 








xRingbufferRemoveFromQueueSetWrite 
BaseType t xRingbufferRemoveFromQueueSetWrite ( 
RingbufHandle t ringbuf, 
QueueSetHandle t xQueueSet) 








vRingbufferReturnitem 
Release the storage for a previously retrieved item. 


void vRingbufferReturnItem ( 

RingbufHandle t ringbuf, 

void *item) 
When we make a call to xRingbufferReceive() we are supplied a pointer to storage 
that is contained within the ring buffer. That storage is not released until we invoke 


vRingbufferReurnItem(). 


vRingbufferReturnltemFromlSR 

void vRingbufferReturnItemFromISR ( 
RingbufHandle t ringbuf, 
void *item, 
BaseType t *higher prio_task_awoken) 


Page 453 


xRingbufferSend 


Insert an item into the ring buffer. 
BaseType t xRingbufferSend ( 
RingbufHandle t ringbuf, 
void *data, 
size t data_size, 
TickType t ticks to wait) 


* ringbuf —Aring buffer handle. 


* data —Pointer to the data to be inserted into the buffer. 





* data _size — Size of the data to insert into the buffer. 


ticks to wait — Ticks to wait before giving up for enough space to be available 
in the buffer to insert the item. 


xRingbufferSendFromlSR 
Insert an item into the ring buffer from an ISR. 


BaseType t xRingbufferSendFromISR ( 
RingbufHandle t ringbuf, 
void *data, 
size t data_size, 


BaseType t *higher prio task awoken) 
* ringbuf —Arring buffer handle. 


* data — Pointer to the data to be inserted into the buffer. 





* data _size — Size of the data to insert into the buffer. 
¢ higher_prio_task_awoken 


vSemaphoreCreateBinary 
xSemaphoreCreateCounting 
vSemaphoreGive 
xSemaphoreGiveFromlISR 
vSemaphoreTake 


xTaskCreate 
Create a new instance of a task. 
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BaseType t xTaskCreate ( 
pdaTASK CODE pvTaskCode, 
const signed portCHAR *pcName, 
unsigned portSHORT usStackDepth, 
void *pvParameters, 

















unsigned portBASE TYPE uxPriority, 
xTaskHandle *pxCreatedTask) 





* pvTaskCode — Pointer to the task function. In C programming, we can simply 
supply the name of a function or, as has been seen in some samples, the 
address of the name of the function. Apparently these equate to items that are 
close enough to be used interchangeably. 


* pcName — Debugging name of the task. 

* usStackDepth — Size of the stack for the task. 

* pvParameters — Parameters for the task instance. This may be NULL. 
* uxPriority — Priority of the task instance. 


* pxCreatedTask — Reference to the newly created task instance. This may be 
passed in as NULL if no task handle is required to be returned. 


In an ESP32 environment, an example, we might have: 


void myTask(void *parms) { 
// Do something 
vTaskDelete (NULL) ; 

} 


° cd Ren "myTask", 2048, NULL, 5, NULL); 

} 
When a created task is invoked and then decides to end via a return, it is essential that 
the task call vtTaskDelete (NULL) before it completes. Calling this is an indication to 
FreeRTOS that the task is finished and need no longer be considered for context 
switching. Experience seems to show that if we don't do this then the ESP32 will crash. 
In summary, end your return logic in your task functions with: 


{ 
// Previous code here. 
vTaskDelete (NULL) ; 
return; 


Include: 


¢ #include <freertos/FreeRTOS.h> 
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¢ #include <freertos/task.h> 


See also: 


vTaskDelete 
xTaskCreate 


xTaskCreatePinnedToCore 
BaseType t xTaskCreatePinnedToCore ( 





TaskFunction_t pxTaskCode, 
const char * pcName, 

const uintl6 t usStackDepth, 
void *pvParameters, 
UBaseType t uxPriority, 
TaskHandle t *pxCreatedTask, 
const BasType t xCoreID) 


This is a mysterious function that appears to be ESP32 specific. 


When a created task is invoked and then decides to end via a return, it is essential that 
the task call vtaskDelete (NULL) before it completes. Calling this is an indication to 
FreeRTOS that the task is finished and need no longer be considered for context 
switching. Experience seems to show that if we don't do this then the ESP32 will crash. 
In summary, end your return logic in your task functions with: 


{ 
// Previous code here. 
vTaskDelete (NULL) ; 
return; 


} 
In an ESP32 environment, an example, we might have: 


void myTask(void *parms) { 
// Do something 
vTaskDelete (NULL) ; 

} 


main() { 
xTaskCreatePinnedToCore(&myTask, "myTask", 2048, NULL, 5, NULL, 0); 





} 


The xcorerp specifies which core to run on. Choices are 0 (PRO CPU) or 1 (APP CPU) 
to "tskNO_ AFFINITY". 


Include: 
¢ #include <freertos/FreeRTOS.h> 
¢ #include <freertos/task.h> 


See also: 


vTaskDelete 
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vTaskDelay 
Delay a task for a specified number of ticks. 


void vTaskDelay(const TickType t xTicksToDelay) 





The constant called port TICK PERIOD Ms provides the number of ticks in a millisecond. 
If we wished to delay for 1 second, we could then supply 1000 / port TICK_PERIOD MS. 


Include: 





¢ #include <freertos/FreeRTOS.h> 


¢ #include <freertos/task.h> 


See also: 


vTaskDelay 
Timers in FreeRTOS 


vTaskDelayUntil 
Delay a task until a specified absolute time. 


void vTaskDelayUntil ( 


const 
const 





Tick 
Tick’ 


Type _t *pxPreviousWakeTime, 





[Type t xTimeIncrement) 


Note: This is flagged as an un-tested FreeRTOS function. 


This function blocks a task until some absolute time in the future. 


* pxPreviousWakeTime — The base time which the increment will be relative from. 


* xTimeIncrement — The time in ticks which, when added to the 
pxPreviousWakeTime, Will be the time that the task is ready to run again. 


Include: 





¢ #include <freertos/FreeRTOS.h> 


¢ #include <freertos/task.h> 


See also: 


vTaskDelayUntil 
Timers in FreeRTOS 


vTaskDelete 
Delete an instance of a task. 


void vTaskDelete (TaskHandle t pxTask) 
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This function will delete an instance of a task. If the pxTask handle is nutu then the 
current task will be deleted. 


Include: 
¢ #include <freertos/FreeRTOS.h> 
¢ #include <freertos/task.h> 


See also: 


vTaskDelete 


vTaskGetInfo 

void vTaskGetInfo ( 

TaskHandle t xTask, 
TaskStatus_t *pxTaskStatus, 
BaseType t xGetFreeStackSpace, 
eTaskState eState) 








The calculation of the current state that is returned can be time consuming, to calculate 
its value, pass in eState with a value of eInvalid. 


The calculation of the minimum amount of free stack space we have seen is also 
expensive so pass in a value of patrRue to retrieve it and pdratse to ignore it. 








The TaskStatus_t contains: 
° TaskHandle t xHandle — 


* const signed char *pcTaskname — 





° UBaseType t xTaskNumber — 


° eTaskState eCurrentState — 





° UBaseType t uxCurrentPriority — 











° UBaseType t uxBasePriority — 





* unsigned long ulRunTimeCounter — 








° StackType t *pxStackBase — 


* unsigned short usStackHighWaterMark — 


xTaskGetCurrentTaskHandle 
Get the current task handle. 


TaskHandle t xTaskGetCurrentTaskHandle() 
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pcTaskGetTaskName 
Get the name of the task. 


char *pcTaskGetTaskName (TaskHandle t xTaskToQuery) 

If we supply NULL for the task handle, we get our own task name. 
uxTaskGetNumberOfTasks 

Get the number of tasks. 


UBaseType t uxTaskGetNumberOfTasks () 


Once we know the number of tasks, we can retrieve the details of them through a call to 
uxTaskGetSystemState(). 





Includes: 
¢ freertos/FreeRTOS.h 
¢ freertos/task.h 


See also: 


Error: Reference source not found 


eTaskGetState 
Retrieve the state of a task. 


eTaskStat TaskGetState(TaskHandle t xTask) 





The possible values are: 
° eReady — 
e eRunning — 
° eBlocked — 
° eSuspended — 


e eDeleted — 


uxTaskGetSystemState 

Note: This is disabled by default. To enable the configUSE_TRACE FACILITY definition in 
FreeRTOSConfig.h must be set to 1. When enabled, we still get an assert as this is 
flagged as an "untested" function. 














Retrieve the task state for all tasks in the environment. 
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UBaseType t uxTaskGetSystemState ( 
TaskStatus_t *pxTaskStatusArray, 





const UBaseType t uxArraySize, 
uint32 t *pulTotalRunTime) 


The TaskStatus_t contains: 
° TaskHandle t xHandle — 
* const signed char *pcTaskname — 
° UBaseType t xTaskNumber — 


° eTaskState eCurrentState — 





° UBaseType t uxCurrentPriority — 








° UBaseType t uxBasePriority — 


* unsigned long ulRunTimeCounter — 





° StackType t *pxStackBase — 
°* unsigned short usStackHighWaterMark — 


The return type is the number of tasks populated. We can call 
uxTaskGetNumberOfTasks () to determine how many tasks are present. 


Includes: 
¢ freertos/FreeRTOS.h 
¢ freertos/task.h 


See also: 


vTaskGetInfo 


xTaskGetTickCount 
Get the current tick count. 


TickType t xTaskGetTickCount () 


Return the number of ticks that have occurred since the task scheduler was started. 





The macro called port TICK PERIOD Ms defines the duration of a single tick in 
milliseconds. 


Include: 
¢ #include <freertos/task.h> 


See also: 


Timers in FreeRTOS 
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xTaskGetTickCountFromlSR 
Get the current tick count from an Interrupt Service Routine. 


TickType t xTaskGetTickCountFromISR() 
Include: 


¢ #include <freertos/task.h> 


vEventGroupDelete 
Delete an event group. 








void vEventGroupDelete (EventGroupHandle t eventGroup) 
Includes: 


¢ #include <freertos/event_groups.h> 


vTaskList 


void vTaskList (char *pcWriteBuffer) 


NOT AVAILABLE 


uxTaskPriorityGet 
Get the priority of the task. 


UbaseType t uxTaskPriorityGet (TaskHandle t xTask) 


vTaskPrioritySet 
void vTaskPrioritySet (TaskHandle t pxTask, UBaseType t uxNewPriority) 


Include: 
¢ #include <freertos/task.h> 


See also: 


Error: Reference source not found 


vTaskResume 
Resume a task that was previously suspended. 


void vTaskResume (TaskHandle t pxTaskToResume) 
Include: 


¢ #include <freertos/task.h> 
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See also: 


vTaskSuspend 


xTaskResumeAIll 
Include: 


¢ #include <freertos/task.h> 


See also: 


vTlaskResumeAll 


vTaskResumeFromiSR 
void xTaskResumeFromISR(TaskHandle t pxTaskToResume) 


Include: 


¢ #include <freertos/task.h> 


vTaskSuspend 
Suspend the given task. 


void vTaskSuspend(TaskHandle t pxTaskToSuspend) 
The identified task is suspended until it is allowed to continue. 
Include: 

¢ #include <freertos/task.h> 


See also: 


vTaskResume 
xTaskResumeAll 


vTaskSuspendaAll 
Include: 


¢ #include <freertos/task.h> 
See also: 


vTaskSuspendAIl 


xTimerChangePeriod 
Change the period of an existing timer. 


BaseType t xTimerChangePeriod ( 
TimerHandle t xTimer, 
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TickType _t xNewPeriod, 
TickType t xBlockTime) 








When a timer is created through a call to xTimerCreate(), we can subsequently change 
the period of that timer. 


* xTimer — The handle to the existing timer. 


* xNewPeriod — The new period value for the timer. 


xBlockTime — The duration that this function can maximally wait for processing. 
Includes: 


¢ #include <freertos/timers.h> 


xTimerChangePeriodFromlISR 
Change the period of an existing timer from within an Interrupt Service Routine. 


BaseType t xTimerChangePeriodFromISR ( 
TimerHandle t xTimer, 

TickType _t xNewPeriod, 

BaseType t *pxHigherPriorityTaskWoken) 








* xTimer — The handle to the existing timer. 


* xNewPeriod — The new period value for the timer. 


pxHigherPriorityTaskWoken — Flag indicating that a context switch should occur. 
Includes: 


¢ #include <freertos/timers.h> 


xTimerCreate 
Create a new timer. 


TimerHandle t xTimerCreate ( 
const char * const pcTimerName, 
const TickType t xTimerPeriod, 
const UBaseType t uxAutoReload, 
void * const pvTimerID, 
TimerCallbackFunction_t pxCallbackFunction) 


* pcTimerName — The name of the timer used for debugging and reporting. 


* xTimerPeriod — The period, measured in ticks, after which the timer should fire. 
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uxAutoReload —A flag which indicates whether or not the timer should restart 
once fired. If restarted, it will start again using the xTimerPeriod value for the 
next interval. 


pvTimer1IpD — Data available to the timer callback function when fired. 


pxCallbackFunction — Function called when the timer expires. The signature of 
this function is: 


void vCallbackFunction(TimerHandle t xTimer) 


The return from the xTimercreate function is a handle that can be used to refer to this 
timer in the future. 


Includes: 


#include <freertos/timers.h> 


xTimerCreateStatic 
TimerHandle t xTimerCreateStatic ( 


const char * const pcTimerName, 


const TickType t xTimerPeriod, 


const UBaseType t uxAutoReload, 


void * const pvTimerID, 


TimerCallbackFunction_t pxCallbackFunction 


StaticTimer t *pxTimerBuffer) 


Includes: 


#include <freertos/timers.h> 


xTimerDelete 


Delete 


an existing timer. 





BaseType t xTimerDelete(TimerHandle t xTimer, TickType t xBlockTime) 


This call deletes a timer that was previous created by an xTimerCreate() Call. 
Following a successful call, we should not attempt to refer to this timer again. 


xTimer — The handle to the timer to delete. 


xBlockTime — The length of timer we should block waiting for the delete to be 
processed. 


Includes: 
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#include <freertos/timers.h> 


pcTimerGetName 
Get the name of the timer. 


const char * pcTimerGetName (TimerHandle t xTimer) 





When we created a timer using xTimerCreate() we supplied a name identity for the 
timer. This call returns that value. 


* xTimer — The handle to a previously created timer. 
Includes: 


¢ #include <freertos/timers.h> 


xTimerGetExpiryTime 
Note: Not implemented in ESP-IDF. 


Return the time at which the timer will fire. 





TickType t xTimerGetExpiryTime (TimerHandle t xTimer) 


For an active timer, this call will return the tick value at which the timer will fire. This is 
an absolute value. If we want to know how many ticks in the future this will be, we can 
obtain the current tick value and subtract one from the other. 


* xTimer — The handle to a previously created timer. 
Includes: 
¢ #include <freertos/timers.h> 


See also: 


xTaskGetTickCount 


xTimerGetPeriod 
Note: Not implemented in ESP-IDF. 
Get the period value for a timer. 


TickType t xTimerGetPeriod(TimerHandle t xTimer) 


Return the period value for the timer. This is the value passed in when xcreateTimer () 
was initially created. It is a relative value rather than an absolute expiry time. If the 
timer is configured to restart, this is the value that will be used to fire the next instance 
of the timer. 


* xTimer — The handle to a previously created timer. 
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Includes: 


¢ #include <freertos/timers.h> 


pvTimerGetTimerDaemonTaskHandle 
Retrieve the task handle to the timer daemon. 


TaskHandle t xTimerGetTimerDaemonTaskHandle (void) 


Behind the scenes, FreeRTOS is running a task that is managing the timers. There 
may be times when we want to get access to the handle for this task. This API returns 
the handle. 


Includes: 


¢ #include <freertos/timers.h> 


pvTimerGetTimerID 
Retrieve the data associated with an instance of the timer. 


void *pvTimerGetTimerID(TimerHandle t xTimer) 


When a timer is created, we can associate data with it. We can also update that data at 
a later timer. This API retrieves the current value of the data. 


* xTimer — The handle to a previously created timer. 
Includes: 


¢ #include <freertos/timers.h> 


xTimerlsTimerActive 
Determine if the timer is active. 


BaseType t xTimerIsTimerActive (TimerHandle t xTimer) 





An active timer is one that is ticking down to a time when it will fire. 
* xTimer — The handle to a previously created timer. 
Includes: 


¢ #include <freertos/timers.h> 


xTimerPendFunctionCall 
Execute a function on the timer daemon task. 
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BaseType t xTimerPendFunctionCall ( 
PendedFunction _t xFunctionToPend, 
void *pvParameterl, 
uint32 t ulParameter2, 

TickType t xTicksToWait) 


Calling this API causes the function supplied to execute on the timer daemon task. 


* xFunctionToPend — The function to be executed in the context of the timer 
daemon task. The function has the following signature: 


void vPendableFunction(void *pvParameterl, uint32_ t ulParameter2) 


* pvParameter1 —A parameter to be passed to the function. 





* ulParameter2 —A parameter to be passed to the function. 





* xTicksTowait —A duration to wait for the function to be started. 
Includes: 


¢ #include <freertos/timers.h> 


xTimerPendFunctionCallFromlSR 
BaseType t xTimerPendFunctionCallFromISR ( 
PendedFunction _t xFunctionToPend, 
void *pvParameterl, 
uint32 t ulParameter2, 
BaseType t *pxHigherPriorityTaskWoken) 


Includes: 


¢ #include <freertos/timers.h> 


xTimerReset 
Reset the value of the timer. 


BaseType t xTimerReset (TimerHandle t xTimer, TickType t xBlockTime) 





Reset the value of the timer to start ticking from the time when this API was called with 
the period associated with the timer. 


* xTimer — The handle to a previously created timer. 
* xBlockTime — The time to wait for the reset to complete. 
Includes: 


¢ #include <freertos/timers.h> 


Page 467 


xTimerResetFromlSR 

BaseType t xTimerResetFromISR ( 
TimerHandle t xTimer, 
BaseType t *pxHigherPriorityTaskWoken) 


vTimerSetTimerlD 
Note: Not implemented in ESP-IDF. 


Associate data with the timer. 


void vTimerSetTimerID (TimerHandle t xTimer, void *pvNewID) 

* xTimer — The handle to a previously created timer. 

* pvNewID — Reference to data to be associated with the timer. 
Includes: 


¢ #include <freertos/timers.h> 


xTimerStart 
Start a timer ticking. 


BaseType t xTimerStart (TimerHandle t xTimer, TickType t xBlockTime) 
The timer can be stopped before expiration with a call to xTimerStop(). 
* xTimer — The handle to a previously created timer. 
* xBlockTime — The time to wait for the start request to complete. 
Includes: 


¢ #include <freertos/timers.h> 


xTimerStartFromlSR 

BaseType t xTimerStartFromISR ( 
TimerHandle t xTimer, 
BaseType t *pxHigherPriorityTaskWoken) 


Includes: 


¢ #include <freertos/timers.h> 


xTimerStop 
Stop a timer ticking. 


BaseType t xTimerStop(TimerHandle t xTimer, TickType t xBlockTime) 
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* xTimer — The handle to a previously created timer. 


* xBlockTime — The time to wait for the stop request to complete. 





Includes: 


¢ #include <freertos/timers.h> 


xTimerStopFromliSR 

BaseType t xTimerStopFromISR ( 
TimerHandle t xTimer, 
BaseType t *pxHigherPriorityTaskWoken) 


Includes: 


¢« #include <freertos/timers.h> 


List Processing 


vListinitialise 
Initialize a list. 


void vListInitialise(xList * const pxList) 


The pxList Is a list that should be initialized. 


vListlnitialiseltem 
Initialize an item for insertion into a list. 





void vListInitialiseItem(xListItem * const pxItem) 


Initialize an item that can be added to a list. 


vListInsert 
Insert an item into a list. 


void vListInsert(xList * const pxList, xListItem * const pxNewListItem) 


vListInsertEnd 
Insert an item at the end of a list 





void vListInsertEnd( xList * const pxList, xListItem * const pxNewListItem) 
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Sockets APIs 

For the TCP/IP protocol, the programming API originally developed for the Unix platform 
and written in C was called "sockets". The notion of a socket is that it logically 
represents an endpoint of a network connection. A sender of data sends data through 
the socket and the receiver of data receives data through the socket. The 
implementation of the "socket" itself is provided by the libraries but the logical notion of 
the socket remains. You will find yourself working with an "instance" of a socket and 
you should think of it as an opaque data type that refers to a communication link. 


Sockets remains the primary API and is present in the majority of languages. Here we 
discuss some of the variants for some of the more common languages. 
See also: 


TCP/IP Sockets 


accept 
Accept an incoming request. 


int accept (int socket _fd, struct sockaddr *addr, socklen _t *addrlen) 
Here we can block waiting for an incoming connection request from the server socket. 


We will return immediately if there is a client connection awaiting acceptance. The 
address of the client is returned to us along with its length. 














If we try and accept too many concurrent sockets, the ESP32 may return ENFrILE to 
indicate that we have an overflow. 


The return is the accepted socket connection to the client or -1 if an error. 


See also: 


TCP/IP Sockets 
man(2) — accept 


bind 
Associate a socket with an address. 


int bind(int s, const struct sockaddr *name, socklen_t namelen) 


The name parameter is the socket address to be bound to the socket. The namelen 
provides the length of the address. If the sin add.s addr iS htonl (INADDR_ANy) then we 
are being a server listening on any incoming IP address. 


A return of < 0 on error. 


Here is an example of us defining ourselves as a server: 
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struct sockaddr _in serverAddr; 

serverAddr.sin_ family = AF_INET; 
serverAddr.sin_addr.s_ addr = htonl(INADDR_ ANY); 
serverAddr.sin_ port = htons (80); 





int rc = bind(serverSocket, (struct sockaddr *) &serverAddr, sizeof (serverAddr) ); 


If we have bound a socket to a local port and then close that bound socket, the port 
number remains reserved for a period of time to "cleanup" any in-flight traffic. This 
prevents the socket from being re-used and a bind() attempt can result in an "address 
already in use" error. We can request that the bind() succeed even if the port is in this 
timed wait state. We do this by running: 

















setsockopt (s, SOL SOCKET, SO REUSEADDR, &(int){ 1 }, sizeof(int)); 














which sets the sockets level "so _REUSEADDR" flag. 


See also: 


TCP/IP Sockets 
man(2) — bind 


close 
Close the corresponding socket. 


int close(int s) 


Close the socket. After closing a socket, no further sockets APIs should be called 
against it. This is the last call in the chain. Take care to realize that when a socket is 
created with the socket () API call the return is a socket handle that is also known as a 
file descriptor. A socket handle is unique only for the lifetime of the socket. For 
example, if you call socket (), you might get back a handle that has a value of 3. While 
that socket is alive, no other caller of socket () will be issued the same handle. 
However, once you close the socket (), it is entirely possible that the next caller of 
socket () Will itself be issued the value of 3 because, at that time, the socket handle is 
unused. The reason for spending time on this is that if you are saving socket handles it 
is not difficult to close a handle and then forget that you have closed it and later make a 
sockets API call against the value of the handle when in fact it has been assigned to a 
different socket in the intervening time period. No technical errors will be thrown as at 
the time you are making a socket API call, it is indeed a valid socket handle you are 
using ... it just happens to not be the one your were expecting to use. 


See also: 
man(2) — close 


socket 
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closesocket 
Close the corresponding socket. 


closesocket (int s) 


Close the socket. 


connect 
Connect to a server. 


int connect (int sockFd, const struct sockaddr *partnerAddr, socklen_t addrlen) 


Connect the socket to a partner. The address of the partner is supplied in the 
partnerAddr field. This is a client initiated call and is expected to connect with a 
listening server. 


For example: 


struct sockaddr _in serverAddress; 

serverAddress.sin family = AF_ INET; 

inet_pton(AF INET, "192.168.1.200", &serverAddress.sin_addr.s_ addr); 
serverAddress.sin port = htons (9999) ; 








int rc = connect(sock, (struct sockaddr *)&serverAddress, sizeof (struct sockaddr_in)); 
Includes: 
¢ #include <lwip/sockets.h> 
See also: 
man(2) — connect 


fcntl 
Perform control functions. 


fentl(int s, int cmd, int val) 


We can set control functions on sockets here. 




















Command Value Description 
F_SETFL O NONBLOCK __ |Set the socket non blocking. 
See also: 
man(2) — fentl 
freeaddrinfo 


Release storage allocated by getaddrinfo(). 
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void freeaddrinfo(struct addrinfo *res) 
Includes: 
¢ #include <lwip/netdb.h> 


See also: 


getaddrinfo 


getaddrinfo 


Build an address structure for a desired target. 


int getaddrinfo ( 
const char *node, 
const char *service, 
const struct addrinfo *hints, 
struct addrinfo **res) 


The node parameter is the host-name if the target server. The service is the name of a 
service used to look-up the target port number. It isn't clear how that would work on an 


ESP32. Where would the service to port mappings be kept? 


The hints provides a filter for what to return. | can be nut. If it is supplied, it is a 
pointer to a struct addrinfo with the following fields filled in: 


The ai family can be one of: 
¢ AF_INET 
¢ AF_INET6 
¢ AF_UNSPEC 
The ai_socktype can be one of: 
* SOCK_STREAM 
* SOCK_DGRAM 


The addrinfo structure is defined as follows: 


struct addrinfo { 


int ai_flags; 
int ai_ family; 
int ai_socktype; 
int ai_ protocol; 
socklen t ai_addrlen; 


struct sockaddr *ai_addr; 
char *ai canonname; 
struct addrinfo *ai_next; 
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A return code of 0 indicates success otherwise it returns an error code. Note that errno 
is not used as that is not thread safe. 


The res pointer points to an allocate struct addrinfo storage area that must be 
subsequently released with a call to freeaddrinfo(). 


The struct sockaddr is common cast to a struct sockaddr in which is defined as: 


struct sockaddr_in { 


short sin family; 
unsigned short sin_port; 
struct in_addr sin_addr; 
char sin_zero[8]; 


}; 





struct in_addr { 
unsigned long s_ addr; 


}; 


What this means is that the IP address can be found at var.sin addr or 


var.sin_addr.s_ addr. 
Includes: 
¢ #include <lwip/netdb.h> 


See also: 


freeaddrinfo 
gethostbyname 
gethostbyname_r 
man(3) — getaddrinfo 





gethostbyname 
Look-up a host name through name resolution. 


struct hostent *gethostbyname(const char *name) 


Most likely a wrapper around the Iwip dns_gethostbyname () implementation provided by 
the underlying Ilwip implementation. 


A pointer to a struct hostent is returned. This is a buffer maintained by the network 
layer and will be changed in the next call. The members of a struct hostent are: 


























Member Description 

char *h_name The name of the host. 

char **h aliases An array of alternative names. Last entry is a NULL pointer. 

int h_addrtype The type of addresses. One of AF_INET or AF_INET6. 

int h_ length The length of an address in bytes. 

char **h addr list An array of network addresses for the host. Last entry is a NULL pointer. 
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Includes: 
¢ #include <lwip/netdb.h> 


See also: 


dns_getserver 
dns_setserver 

inet_ntop 

inet_pton 

LWIP Wiki — DNS 
man(3) — gethostbyname 





gethostbyname_r 
Are-entrant version of name resolution. 


int gethostbyname r ( 
const char *name, 
struct hostent *ret, 
char *buf, 
size t buflen, 
struct hostent **result, 
int *h_errnop) 


See here for an example of use. 


See also: 


man(3) — gethostbyname_r 





getpeername 
Retrieve the address associated with the partner/peer to which the socket is connected. 


int getpeername(int s, 
struct sockaddr *peerAddr, 
socklen_ t *namelen) 


Note that namelen must be primed with the size of the available address buffer. 


See also: 


man(2) — getpeername 





getsockname 
Retrieve the current local address to which the socket is bound. 


getsockname(int s, 
struct sockaddr *name, 
socklen_t *namelen) 
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Note that namelen must be primed with the size of the available address buffer. 


See also: 


man(2) — getsockname 





getsockopt 

int getsockopt(int s, 
int level, 
int optname, 
void *optval, 
socklen_t *optlen) 


An important example of using this function is to retrieve the last error associated with 
the socket. The following code fragment illustrates this: 


int espx last _socket_errno(int socket) { 
int ret = 0; 
u32_t optlen = sizeof (ret); 
getsockopt (socket, SOL SOCKET, SO ERROR, &ret, é&optlen); 
return ret; 











} 
See also: 
man(2) - getsockopt 


htonl 
Convert a host formatted long integer to network byte order. 


uint32 t htonl(uint32 t netLong) 
See also: 
man(3) — htonl 


htons 
Convert a host formatted short integer to network byte order. 


uintl6 t htons(uintl6 t hostShort) 
See also: 
man(3) — htons 


inet_ntop 
Convert an IP address structure into a character string. 


char *inet ntop(int af, const char *src, char *dst, socklen_t size) 


The af parameter specified the address family. It may have a value of: 
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* ar INET —IPv4 network addresses. 








* aF_INnET6 —|IPv6 network addresses. 


The src is the pointer to the address structure. The dst is the buffer that will be filled 
with the text and size is the length of that buffer available to be filled. For ar 1net, the 
buffer should be at least INET _ADDRSTRLEN bytes long while for ar_1netTé6, it should be at 
least INET6 ADDRSTRLEN bytes long. 




















Includes: 
¢ #include <lwip/sockets.h> 
See also: 
man(3) — inet_ntop 


inet_pton 
Convert an IP address from string to binary form. 


int inet _pton(int af, const char *src, void *dst) 
The af parameter is the address family. It must be one of: 


* aF_iIneET—IPv4 network address. 








* AF INET6 —|IPv6 network address. 


The src is the pointer to a null terminate string that represents the text format of the 
address. 


Returns 1 on success. 
Includes: 


¢ #include <lwip/sockets.h> 


See also: 
man(3) — inet_pton 


ioctlsocket 
ioctl(int s, long cmd, void *argp) 


listen 
Start listening for incoming connections. 


int listen(int socket _fd, int backlog) 
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If we are bound as a server, we will start to listen for incoming connections requests on 
the socket. The backlog parameter defines how many sockets we can keep a handle to 
before we accept them. 


A return value < 0 means an error. 


See also: 


TCP/IP Sockets 
man(2) — listen 


read 
Receive data from a partner. 


ssize t read(int s, void *mem, size t len) 


Similar to the recv() function. 


See also: 
recv 
recvfrom 
man(2) — read 
recv 


Receive data from a partner. 


ssize t recv(int s, 

void *mem, 

size t len, 

int flags) 
This function returns the number of bytes actually received. A value of -1 indicates an 
error. A value of zero indicates the partner having closed the connection. 


The flags is the boolean combination of: 





* MSG CMSG CLOEXEC — 











* MSG DonTWwAIT — Indicate that we don't want to block waiting for data. If there is 
no data immediately available for us to receive, we return -1 to indicate an error 
and the error code is "EAGAIN". 








° MSG ERRQUEUE — 














* MSG OOB— 











e MSG_ PEEK —_— 





* MSG TRUNC — 








° MSG WAITALL — 
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Includes: 
¢ #include <lwip/sockets.h> 


See also: 


read 
recvfrom 


man(2) — recv 


recvfrom 
Receive a datagram from another machine/device. 


ssize t recvfrom(int sock, 

void *mem, 

size t len, 

int flags, 

struct sockaddr *from, 

socklen t *fromlen) 
The sock Is a socket handle that was previously opened by calling socket (). The memis 
a pointer to a buffer that will hold the incoming data. The 1en parameter supplies the 
length of the buffer. The from is a pointer to a storage area that will hold the address of 
the partner and fromien will be the length of that address. On initial call, it should 
contain the length of the from address. If we don't need the return address of the caller, 


we can supply NULL for both from and fromlen. 
The flags can be specified as: 
* msc pontwart — Don't block waiting for a message not yet arrived. 


* msc _ooB — Check for an out of band message. 





* MSG PEEK — Receive the first message without consuming it. 











The return value is the number of bytes actually received or -1 on an error. 
Includes 
¢ #include <sys/types.h> 


See also: 


read 
recv 
socket 
sendto 


man(2) — recvfrom 
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select 
Check for data available for reading or writing. 


int select (int maxfdpl, 
fd_set *readset, 
fd_set *writeset, 
fd_set *exceptset, 
struct timeval *timeout) 


The notion of "ready" is that an operation could be performed without blocking. 
The maxfdp1 is the maximum value of the file descriptor plus 1. 


On some Linux systems, to use selected, one would include <sys/select.h>. In ESP- 
IDF that is not present but does not appear to be needed. 


Each of the fa_set variables defines a set of file descriptors. To include a file descriptor 
inaset we canrun FD SET(fd, &set). To remove an entry we can call Fp cLR (fd, 
&set). To test ifa file descriptor is ina set we can run FD ISSET(fd, *set) and to clear 
a complete set we can run FD ZERO(é&set). If we aren't interested in some of the sets, 
we can supply NULL to have them ignored. 











If timeout is nuL1, then there will be no timeout and select will wait indefinitely. If both 
fields in the timeval are O, then we return immediately. 


On return, select () returns the number of bits set in the various sets (which may be 0 if 
there was a timeout). An error of -1 is returned on an error. 


A socket that is a server socket is considered "ready" if a call to accept () would not 
block. This socket should be supplied in the readset. 


Take care with the first parameter. This is the number of file descriptor bits to check in 
the file descriptor mask set. If the highest file descriptor value we have is "n" then the 
number of file descriptor bits we are examining is "n+1". 


See also: 


Using select() 


man(2) — select 


send 
Send a set of bytes down the socket to the partner. 


ssize t send(int s, const void *dataptr, size t size, int flags) 
The data pointed to by dataptr for size bytes is transmitted. 
See also: 

man(2) — send 
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sendmsg 
ssize t sendmsg(int s, const struct msghdr * msg, int flags) 


See also: 
man(2) — sendmsg 


sendto 
Send data to a UDP partner. 


ssize t sendto(int sock, 

const void *dataptr, 

size t size, 

int flags, 

const struct sockaddr *to, 

socklen t tolen) 
The sock is the socket handle that was previously opened by a call to socket (). The 
dataptr is a pointer to a buffer of data that we wish to send. The size is the size of the 
datagram that we wish to send. It can be a maximum of 64K. The to is the address of 


the destination of the message and tolen is the length of the address structure. 
The flags can be one or more of: 

* msc pontwart — Do not wait if waiting would be needed. 

* MSG ooB — Send a message out of band. 
The return is the number of bytes actually sent or -1 on an error. 


See also: 


recvfrom 
socket 


man(2) — sendto 


setsockopt 

int setsockopt (int s, 
int level, 
int optname, 
const void *optval, 
socklen _t optlen) 


The options that are anticipated to be available are: 


* TCP NODELAY — Disable the Nagle algorithm. 

















* SO KEEPALIVE — Enable liveness pinging. 











See also: 
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man(2) — setsockopt 





shutdown 
Shutdown parts of a socket. 


int shutdown(int s, int how) 

Shutdown all or part of the socket. 

The socket is shutdown based on the how parameter which may be one of: 
* sHUT RD —No further receives are allowed. 


* sHUT wR —No further writes are allowed. 





* SHUT _RDWR — No further reads or writes are allowed. 
See also: 
man(2) — shutdown 


socket 
Create a new socket for the specific domain, type and protocol. 


int socket (int domain, int type, int protocol) 
Domain can be one of: 

° ar InET— TCP/IP 

¢ Others... 





Type can be one of: 


- SOCK_STREAM 
- SOCK _DGRAM 
- SOCK _RAW 


Protocol can be one of: 


¢ IPPROTO_IP 

« |IPPROTO_TCP 

* IPPROTO_UDP 
Acommon usage pattern is: 








int sock = socket (AF _ INET, SOCK STREAM, IPPROTO_ TCP) 
Returns a new socket descriptor or a value < 0 on error. 
Includes: 


¢ #include <lwip/sockets.h> 
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See also: 


TCP/IP Sockets 
man(2) — socket 


write 


ssize t write(int s, const void *dataptr, size t size) 
See also: 
man(2) — write 


writev 
See also: 


man(2) — writev 


Socket data structures 


Sockets - struct sockaddr 





Sockets - struct sockaddr_in 





¢ sin_family —AF_INET 


* sin_port 


* struct in_addr sin addr -— This structure has a member called s_ addr which is 
an IP address. Special values have special meanings. For example INADDR_ANY 


is any address. 


Working with WiFi 


In the ESP32 environment, we include the header <esp_wifi.h> which provides the 


signatures for the WiFi functions we will be using. Prior to working with any WiFi 
components, we want to call esp wifi _init(). This function initializes the WiFi 
subsystem. Internally it will allocate resources. We have a partner function called 


esp wifi _deinit() which will destroy our WiFi environment and release the resources. 
We should not call any other WiFi functions prior to esp wifi _init() and call no further 
WiFi functions following an esp wifi _deinit(). There is a mandatory parameter to the 
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esp wifi init () whichis a pointer to an instance of wifi init config t. Wecan 
supply a useful default to this call using the wirI_INIT CONFIG DEFAULT macro. 








wifi init config t config = WIFI_INIT CONFIG DEFAULT (); 
err = esp wifi init (&config); 


Since an ESP32 can be both a station and an access point, that means it has two 
interfaces. Two interfaces means two distinct mac addresses. We can set or get the 
values for these 6 byte mac addresses using esp wifi set mac() and 

esp wifi get _mac(). The first parameter of these calls defines which interface we wish 
to interact. The value can either be wir1_1F sta for the station interface or WIFI IF AP 
for the access point interface. 


If we are acting as an access point, we can ask what stations are connected to us with a 
Call to esp wifi get station list(). This returns us a list of stations that is based on 
the ESP32 queuing structure. 


Once we have performed an access point scan, the ESP32 has a notion of the access 
points out there. We can then ask for a copy of this information. We need to 
understand that each access point is identified by a record of type wifi ap record t 
which is composed of: 


uint8 t bssid[6] 
uint8 t ssid[32] 
uint8 t primary 


wifi second chan _t second 





int8 t rssi 





wifi_auth_mode_t authmode 


When we call esp wifi get station list () we pass in a pointer to storage which will 
be populated by these records. We also pass in the maximum number of records we 
will accept. On return, we are told how many records were populated. We are 
managing the storage for these records and ESP32 neither allocates nor releases this 
data. 


For example: 


wifi_ap record _t apList[10]; 

uintl6 t count = 10; 
esp_wifi_get_ station _list(&count, apList); 

printf ("Number of stations populated = %d\n", count); 
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DNS 
The DNS component of ESP32 is provided by the underlying LWIP implementation. 


See also: 


lwip — DNS — Doxygen 





dns_getserver 
Retrieve one of the defined DNS servers. 


const ip addr t dns getserver(u8 t numdns) 

* numdns — The index of the defined DNS server. ESP32 defined 0 and 1. 
Includes: 

¢ #include <lwip/dns.h> 


See also: 


gethostbyname 
lwip — DNS — Doxygen 





dns_setserver 
Set one of the defined DNS servers. 


void dns_setserver(u8 t numdns, const ip addr _t *dnsserver) 
* numdns — The index of the defined DNS server. ESP32 defines 0 and 1. 


Here is an example of usage: 


ip _addr_t dnsserver; 

inet _pton(AF INET, "8.8.8.8", &dnsserver) ; 
dns_setserver(0, &dnsserver); 

inet pton(AF INET, "8.8.4.4", &dnsserver) ; 
dns_setserver(l, &dnsserver); 








Includes: 
¢ #include <lwip/dns.h> 


See also: 


gethostbyname 
lwip — DNS — Doxygen 
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System Functions 


esp_cpu_in_ocd_debug_mode 
Determine if a JTAG debugger is attached to CPU. 


bool esp cpu in ocd debug mode () 





esp_efuse_read_mac 
esp_err t system_efuse read _mac(uint8 t mac[6]) 


esp_get_free_heap_size 
Get the size of the available memory heap. 


uint32 t esp get fr heap size() 








For example 40544. 


As a test | wrote an app that logged the free heap size after boot. This is as of 2016-10- 
05. The result was 195568. 


Includes: 
¢ #include <esp_system.h> 


See also: 


RAM Utilization 


esp_get_idf_version 
Return a representation of the ESP-IDF version against which the application was 
compiled. 


const char *esp get _idf version () 
Includes: 


¢ #include <esp_system.h> 


esp_random 
Get a hardware based random number. 


uint32 t esp random() 
Includes 


¢ #include <esp_system.h> 
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esp_restart 
Restart the system. 


void esp restart () 
Includes 


¢ #include <esp_system.h> 


system_rtc_mem_write 


Storage space for saving data during a deep sleep in RTC storage. 


Includes: 


¢ #include <esp_system.h> 


rtc_get_reset_reason 
Get the reset reason for a CPU. 











RESET REASON rtc_get_reset_reason(int cpuNo) 








The RESET REASON that is returned may be one of: 














° NO MEAN — 









































° DEEPSLEEP RESET — 


























* SDIO_RESET — 








° TGOWDT SYS RESET — 














* TGIWDT SYS RESET — 

















° RTCWDT SYS RESET — 








° INTRUSION RESET — 




















° TGWDT CPU RESET — 





* SW _CPU_RESET — 

















° RTCWDT CPU RESET — 























° EXT_CPU_RESET — 
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° RTCWDT BROWN OUT RESET — 


























° RTCWDT RTC RESET — 








software_reset 
void software reset () 


Includes: 


¢ #include <rom/rtc.h> 


software_reset_cpu 
void software reset _cpu(int cpuNo) 


The CPU numbers supplied by cpuNno are 0 for the PRO CPU and 1 for the APP CPU. 
Includes: 


¢ #include <rom/rtc.h> 


system_deep_sleep 
Puts the device to sleep for a period of time. 


void system deep sleep(uint32 microseconds) 
The device goes to sleep and when it awakes, it will start at the user_init location. 
Includes 


¢ #include <esp_system.h> 


system_get_time 
Note: system get _time() has been deprecated. Use gettimeofday() as a replacement. 


Get the system time measured in microseconds since last device start-up. 


uint32 t system _get_time() 
This timer will roll over after 71 minutes. 


Note: Experimentation seems to show that as of 2016-10, the timer does not tick until 
after a call to esp wifi init(). 


Includes: 
¢ #include <esp_system.h> 


See also: 
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Timers and time 
gettimeofday 


system_restore 
Reset some system settings to defaults. 


void system restore () 
The settings returned to defaults include: 
¢ wifi_station_set_auto_connect 
¢ wifi_set_phy_mode 
¢ wifi_softap_set_config 
¢ wifi_station_set_config 
* wifi_set_opmode 
Includes 


¢ #include <esp_system.h> 


system_rtc_mem_read 
Read data from RTC available storage. 


Includes: 


¢ #include <esp_system.h> 


system_rtc_mem_write 


Storage space for saving data during a deep sleep in RTC storage. 


Includes: 


¢ #include <esp_system.h> 


system_rtc_mem_read 
Read data from RTC available storage. 


Includes: 


¢ #include <esp_system.h> 
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WiFi 
The WiFi function provide access to the WiFi capabilities of the device. 


See also: 


esp_event_loop_init 
Initialize the WiFi event loop processing and specify an event handler. 





sp_err t esp _event_loop init(system_event_cb _t cb, void *ctx) 





Initialize the WiFi event loop processing. 


The callback function for the event handler is defined as: 





esp err t (*system_event_cb t) (void *ctx, system_event_t *event) 
See also: 


Handling WiFi events 
esp_event_loop_set_cb 


esp_event_loop_set_cb 
Change the event handler used for WiFi events. 


system_event_cb_ t esp event loop set _cbh(system_event_cb_t cb, void *ctx) 





Specify an event handler to be invoked when a WiFi event occurs. The previous event 
handler is returned. 


The callback function for the event handler is defined as: 





esp err t (*system_event_cb t) (void *ctx, system_event_t *event) 
Includes: 
¢ #include <esp_event_loop.h> 


See also: 


Handling WiFi events 
esp_event_loop_init 


esp_wifi_ap_get_sta_list 
esp_err t esp wifi_ap get _sta_list(wifi_sta_list_t *sta) 





esp_wifi_clear_fast_connect 
Not implemented. 


esp err t esp wifi clear fast connect () 
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esp_wifi_connect 
Connect to an access point. 


esp err t esp wifi connect () 





Prior to calling this function we should have: 
¢ Initialized WiFi —esp wifi init () 
¢ Set our mode to be either a station or stationtap — esp wifi set _mode() 
¢ Set our desired access point connection information — esp wifi set config() 
¢ Started the WiFi subsystem — esp wifi start () 


We can disconnect from an access point by calling esp wifi disconnect (). Experience 
seems to show that before we can connect to a new access point, we must first 
explicitly disconnect from a previous access point. 


Includes: 
¢ #include <esp_wifi.h> 
See also: 


Connecting to an access point 
esp_wifi_init 
esp_wifi_set_mode 
esp_wifi_set_config 
esp_wifi_start 
esp_wifi_disconnect 


esp_wifi_deauth_sta 
esp err t esp wifi _deauth_sta(uintl6 t aid) 





esp_wifi_deinit 
Release the ESP32 WiFi environment. 


esp err t esp wifi deinit() 





Includes: 
¢ #include <esp_wifi.h> 
See also: 


esp_wifi_init 
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esp_wifi_disconnect 
Disconnect from an access point. 


esp err t esp wifi disconnect () 





We assume that we have previously connected to an access point using 


esp wifi connect(). 
Includes: 


¢ #include <esp_wifi.h> 


See also: 


Connecting to an access point 
esp_wifi_connect 


esp_wifi_free_station_list 
Release the storage for the previously returned list of stations. 


esp_err t esp wifi free station_list() 





Includes: 
¢ #include <esp_wifi.h> 
See also: 


Working with connected stations 
esp_wifi_get_station_list 


esp_wifi_get_auto_connect 
Determine whether or not auto connect at boot is enabled. 


esp err t esp wifi set auto connect (bool *enabled) 





Includes: 
* esp_wifi.h 
See also: 


Connecting to an access point 
esp_wifi_set_auto_connect 


esp_wifi_get_bandwidth 
Get the current bandwidth. 


esp_err t esp _wifi_get_ bandwidth (wifi interface t ifx, wifi_bandwidth_t *bandWidth) 
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Includes: 
¢ #include <esp_wifi.h> 
See also: 


esp_wifi_set_bandwidth 


esp_wifi_get_channel 
Get the current channel. 


esp_err t esp wifi _get_channel(uint8 t *primary, wifi_second_chan_t *second) 





Includes: 
¢ #include <esp_wifi.h> 


See also: 


esp_wifi_set_channel 


esp_wifi_get_config 
Retrieve the current connection information associated with the specified WiFi interface. 





esp err t esp wifi_get_config(wifi_interface_ t interface, wifi_config t *conf) 





The interface is one of: 
* WIFI IF sta— The station interface. 
* WIFI IF ap—The access point interface. 


The conf parameter is populated with the current configuration. See the details of 
esp wifi set config for the nature and content of this data type. 


Includes: 
¢ #include <esp_wifi.h> 


See also: 


. esp_wifi_set_config 


esp_wifi_get_country 
Retrieve the currently configured WiFi country. 


esp err t esp wifi_get_country(wifi_ country t *country) 





The default WiFi country is China. Allowable values are: 


° WIFI COUNTRY CN 


Page 493 


° WIFI COUNTRY JP 


° WIFI COUNTRY US 








: WIFI COUNTRY EU 
Includes: 

¢ #include <esp_wifi.h> 
See also: 


esp_wifi_set_country 


esp_wifi_get_mac 
Retrieve the current MAC address for the interface. 


esp err t esp wifi_get_mac(wifi_interface t interface, uint8 t mac[6]) 








The interface is one of: 

* WIFI IF sta— The station interface. 

* WIFI IF ap—The access point interface. 
Includes: 

¢ #include <esp_wifi.h> 
See also: 


esp_wifi_set_mac 


esp_wifi_get_mode 
Get the WiFi operating mode. 


esp_err t esp wifi_get_mode(wifi_mode_t *mode) 





Get the operating WiFi mode. The choices available are: 
* WIFI MODE NULL — No WiFi. 
* WIFI MopE sta—A station. 


* WIFI MODE AP —An access point. 














* WIFI MobE apsta— Both a station and an access point. 
Includes: 
¢ #include <esp_wifi.h> 


See also: 


. Setting the operation mode 
. Station configuration 


Page 494 


esp_wifi_set_mode 
esp_wifi_set_config 


esp_wifi_get_promiscuous 
esp err t esp wifi_get_ promiscuous (uint8 t *enable) 





Includes: 
¢ #include <esp_wifi.h> 
See also: 


esp_wifi_set_promiscuous 


esp_wifi_get_protocol 
Get the 802.11 protocol (b/g/n). 


esp err t esp wifi_get_ protocol (wifi_interface t ifx, uint8 t *protocolBitmap) 





The possible protocols are: 
¢ WIFILPROTOCOL_11B 
¢ WIFILPROTOCOL_11G 
¢ WIFIL_PROTOCOL_11N 
¢ WIFILPROTOCOL_LR 
Includes: 


¢ #include <esp_wifi.h> 


See also: 


esp_wifi_set_protocol 


esp_wifi_get_ps 
Get the power save type. 


esp err t esp wifi_get_ps(wifi_ps_ type t *type) 





The type of power save will be one of: 
© WIFI PS NONE — 


° WIFI PS MODEM — 





* WIFI PS LIGHT — 
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* WIFI PS MAC— 
Includes: 

¢ #include <esp_wifi.h> 
See also: 


esp_wifi_set_ps 


esp_wifi_get_station_list 


Get the list of stations connected to ESP32 when it is behaving as an access point. 


esp_err t esp wifi get station list(wifi_sta_list_t **station) 





The structure of a"struct station info" Is: 


STAILQ ENTRY (station info) next 
uint8 t bssid[6] 





To walk through this list we can use the following algorithm: 


wifi_sta_list_t *stations; 
// 
while (stations != NULL) { 
printf ("bssid: %.2x:%3.2x:%.2xK:%.2x%:%3.2x:%.2x\n", 
stations->bssid[0],stations->bssid[1],stations->bssid[2] 


stations->bssid[3],stations->bssid[4],stations->bssid[5]); 


stations = STAILQ NEXT(stations, next); 





} 
Includes: 

¢ #include <esp_wifi.h> 
See also: 


Working with connected stations 
esp_wifi_free_station_list 
tcpip_adapter_get_sta_list 


esp_wifi_init 
Initialize the ESP32 WiFi environment. 


esp err t esp wifi_init(wifi_init config t *config) 





This API call should be invoked before all other WiFi related calls. 


wifi init config _t contains: 
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The 


void * event q 
uint8 t rx_ba_ win 
uint8 t rx_ba win 


uint8 t rx_ba_ win 


Amacro called WIFI INIT CONFIG DEFAULT Can be used to initialize the configuration 
structure. For example: 





wifi init config _t config = WIFI_INIT CONFIG DEFAULT (); 
esp wifi _init(&config); 





Includes: 
¢ #include <esp_wifi.h> 
See also: 


Initializing the WiFi environment 
esp_wifi_start 
esp_wifi_deinit 


esp_wifi_kick_station 
Kick all stations or a named station that are connected to the ESP32 when it is behaving 
as an access point. 


esp err t esp wifi_kick_station(uintl6 t aid) 





The aid identifies a station. What this means is not yet known. If its value is zero, then 
all stations are kicked otherwise just the identified station is kicked. 


Includes: 
¢ #include <esp_wifi.h> 
See also: 


Working with connected stations 


esp_wifi_reg_rxcb 


esp err t esp wifi_reg rxcb(wifi_interface t ifx, wifi_rxcb_t fn) 





Includes: 


¢ #include <esp_wifi.h> 
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esp_wifi_scan_get_ap_records 
Retrieve the access points found in a previous scan. 


esp err t esp wifi_get_ap_ records(uintl6 t *number, wifi_ap record_t *apRecords) ; 





The apList is a contiguous chunk of storage capable of holding objects of type 
wifi ap record _t. The number of such records is the initial value of the number 
parameter. On return, the actual number of items will be updated. A wifi ap record t 
record contains: 





uint8 t bssid[6] 
uint8 t ssid[32] 
uint8 t primary 


wifi second chan _t second 


int8 t rssi 





wifi_auth_mode_ t authmode 


The authmode can be one of: 


° WIFI AUTH OPEN — 





° WIFI AUTH WEP — 
° WIFI AUTH WPA PSK— 


° WIFI AUTH WPA2 PSK— 




















° WIFI AUTH 


= 


PA WPA2 PSK — 





Includes: 


¢ #include <esp_wifi.h> 


See also: 


Scanning for access points 
esp_wifi_scan_stop 


esp_wifi_scan_get_ap_num 
Retrieve the count of found access points from a previous scan. 


esp err t esp wifi _scan_get_ap_num(uint1l6 t *number) 





Retrieve the number of discovered access points from the previous scan. We need to 
be careful that the scan has completed before getting the count. 


Includes: 
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¢ #include <esp_wifi.h> 
See also: 


Scanning for access points 


esp_wifi_scan_start 
Scan for access points. 


esp err t esp wifi _scan_start(wifi_scan_config t *conf, bool block) 





Govern how the scan should be performed. The wifi scan config t contains the 
following fields: 


char * ssid 
uint8 t * bssid 
uint8 t channel 


bool show_hidden 


The block parameter defines whether or not this call blocks until the data is available. 


The results of a WiFi scan are stored internally in ESP32 dynamically allocated storage. 
The data is returned to us when we call esp wifi get ap list () which also releases 
the internally allocated storage. As such, this should be considered a destructive read. 





Includes: 
¢ #include <esp_wifi.h> 
See also: 


Scanning for access points 
esp_wifi_scan_stop 


esp_wifi_scan_stop 
Stop an access point scan that is in progress. 


esp err t esp wifi scan stop() 





By calling esp wifi_scan_start(), we can request that a WiFi scan be performed in the 
background. Should we wish to interrupt or stop that activity, this function can be used. 


Includes: 
¢ #include <esp_wifi.h> 


See also: 
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Scanning for access points 
esp_wifi_scan_start 

Error: Reference source not found 
esp_wifi_set_config 


esp_wifi_set_auto_connect 
esp err t esp wifi set auto connect (bool enabled) 





Includes: 
¢ #include <esp_wifi.h> 
See also: 


Connecting to an access point 
esp_wifi_get_auto_connect 


esp_wifi_set_bandwidth 
Set the current bandwidth. 


esp err t esp wifi set bandwidth ( 








wifi interface _t interface, 
wifi bandwidth _t bandWidth) 


The interface is one of: 

* WIFI _1r_sta-—The station interface. 

* WIFI IF ap—The access point interface. 
The bandwidth parameter can be one of: 


° WIFI _BW_HT20— 





° WIFI BW _HT40— 
Includes: 

¢ #include <esp_wifi.h> 
See also: 


esp_wifi_get_bandwidth 


esp_wifi_set_channel 
esp err t esp wifi_set_ channel (uint8 t primary, wifi_second_chan_t second) 





Includes: 
¢ #include <esp_wifi.h> 
See also: 


esp_wifi_get_channel 
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esp_wifi_set_config 
Set the WiFi interface configuration. 


esp err t esp wifi set config ( 








wifi interface _t interface, 
wifi config t *conf) 


The interface is one of: 
* WIFI _IF sta— The station interface. 
* WIFI IF ap— The access point interface. 


The choice of which interface will be used will be dependent on whether or not we are 
being an access point, a station or both. If a station, we will configure the station 
interface, if an access point, we will configure the access point interface and if both, 
then we will configure both interfaces. We should previously have called 


esp wifi set _mode(). 


The wifi config t defines properties of the interface. It is a C language union of 
wifi _ap config t and wifi sta_config t. 


The wi fi_sta_config t contains: 


char ssid[32] 

char password[64] 

bool bssid_ set 
uint8 t bssid[6] 


An example initialization for this structure might be: 


wifi config t staConfig = { 
-sta = { 
.ssid="<access point name>", 
.password="<password>", 
-bssid_set=false 


The wi fi_ap config t contains: 
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char ssid[32] 
char password[64] 
uint8 t ssid _ len 
uint8 t channel 
wifi _auth_mode_t authmode 


uint8 t ssid hidden 





uint8 t max connection 





uintl6 t beacon interval 


If ssid_len Is 0, then look for a string termination character in the ssid field. Otherwise 
if ssid_len Is greater than 0, the value defines the number of bytes in ssid to read for 
the ssid value. 


The channel Is the channel we are using for WiFi. 


The authmode indicates how stations can connect. Options include: 


° WIFI AUTH OPEN 





* WIFI AUTH WEP 
° WIFI AUTH WPA PSK 


* WIFI AUTH WPA2 PSK 

















° WIFI AUTH WPA WPA2 PSK 





The ssid_hidden is 0 meaning that the SSID is broadcast and can be found. 


The max connection is the maximum number of stations that can connect. The default 
is 4. 


The beacon interval is some magic related to WiFi and should have a default value of 
100. 


An example of initialization of this structure might be: 


wifi config t apConfig = { 
-ap = { 

.ssid="<access point name>", 
.password="<password>", 
.ssid_len=0, 
.channel=0, 
.authmode=WIFI AUTH OPEN, 
.ssid_hidden=0, 
-max_ connection=4, 





.beacon_interval=100 


}; 


Includes: 
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¢ #include <esp_wifi.h> 
See also: 


esp_wifi_get_config 
Being an access point 
Station configuration 


esp_wifi_set_country 
Set the WiFi country. 


esp_err t esp wifi_set_country(wifi country t country) 





The default WiFi country is China. Allowable values are: 
* WIFI _COUNTRY_CN-— China. 
* WIFI COUNTRY JP — Japan. 


* WIFI _couNtRY_ us — United States of America. 











* WIFI COUNTRY EU — European Union. 
Includes: 

¢ #include <esp_wifi.h> 
See also: 


esp_wifi_get_country 


esp_wifi_set_mac 
esp err t esp wifi_set_mac(wifi_interface t ifx, uint8 t mac[6]) 





Includes: 
¢ #include <esp_wifi.h> 
See also: 


esp_wifi_get_mac 


esp_wifi_set_mode 
Set the operating mode. 


esp err t esp wifi_set_mode(wifi_mode_t mode) 





Set the operating WiFi mode. The choices are: 


* WIFI MODE NULL — No WiFi. 
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* WIFI MoDE sta—A station. 


* WIFI MODE Ap —An access point. 





* WIFI MobE apsta — Both a station and an access point. 


You will also need to call esp wifi set config () to specify the configuration 
parameters. If we are being an access point, we will not actually start listening for 
stations until after esp wifi start () and if we are being a station, we will not connect to 
an access point until after a call to esp wifi_start() and then esp wifi connect (). 


Includes: 
¢ #include <esp_wifi.h> 
See also: 


Setting the operation mode 
Station configuration 
esp_wifi_get_mode 
esp_wifi_set_config 


esp_wifi_set_promiscuous_rx_cb 
esp err t esp wifi_set_promiscuous_rx_cb(wifi_promiscuous_cb_t cb) 





Includes: 
¢ #include <esp_wifi.h> 


See also: 


esp_wifi_set_promiscuous 
esp err t esp wifi_set_ promiscuous (uint8 t enable) 





Includes: 
¢ #include <esp_wifi.h> 
See also: 


esp_wifi_get_promiscuous 


esp_wifi_set_protocol 
Set the 802.11 protocol (b/g/n) 


esp_err t esp wifi_set_ protocol (wifi_interface t ifx, uint8 t protocolBitmap) 





The allowable protocols are: 
« WIFI_PROTOCOL_11B 
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¢ WIFILPROTOCOL_11G 

¢ WIFILPROTOCOL_11N 

¢ WIFILPROTOCOL_LR 
Includes: 

¢ #include <esp_wifi.h> 
See also: 


esp_wifi_get_protocol 


esp_wifi_set_ps 
Set the power save type. 


esp err t esp wifi_set_ps(wifi_ps type t type) 





The type of power save will be one of: 
* WIFI_PS NONE — 


° WIFI PS MODEM — 





* WIFI PS LIGHT — 





* WIFI PS MAC— 
Includes: 

¢ #include <esp_wifi.h> 
See also: 


esp_wifi_get_ps 


esp_wifi_set_storage 
Define where WiFi configuration will be stored. 


esp_err t esp wifi_set_storage(wifi_ storage t storage) 





The options available are: 


* WIFI STORAGE FLASH — Configuration stored in both flash and RAM. This is the 
default. 








* WIFI STORAGE RAM — Configuration stored in RAM only (not in flash as well). 


The value of this method is that we can choose to save our configuration set by 
esp wifi set _config() to RAM or both flash and RAM. If we save our settings in flash 
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then it is these settings that will be used during an auto connect when we call 
esp wifi set auto connect () to connect at start up. 





Includes: 
¢ #include <esp_wifi.h> 
See also: 


Connecting to an access point 
esp_wifi_set_config 
esp_wifi_set_auto_connect 


esp_wifi_set_vendor_ie 
esp err t esp wifi set vendor ie ( 
bool enable, 





wifi vendor ie type t type, 








wifi vendor ie id t idx, 
uint8 t *vnd_ie) 





Includes: 


¢ #include <esp_wifi.h> 


esp_wifi_set_vendor_ie_cb 
esp err t esp wifi set vendor ie cb( 





esp vendor ie cb t cb, 
void *ctx) 





Includes: 


¢ #include <esp_wifi.h> 


esp_wifi_sta_get_ap_info 
Get information about the access point to which we are connected, 


esp err t esp wifi_sta_get_ap info(wifi_ap record _t *apInfo) 





esp_wifi_start 
Start the WiFi subsystem. 


esp err t esp wifi start () 





Prior to calling this function, we should have called esp wifi init () and configured our 
mode (esp wifi set mode) and interfaces (esp wifi set config). If we are an access 
point, then after calling this function, we will start to accept incoming client connections. 


Includes: 
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¢ #include <esp_wifi.h> 
See also: 


Starting up the WiFi environment 
esp_wifi_stop 

esp_wifi_init 

esp_wifi_set_mode 


esp_wifi_stop 
Stop the WiFi subsystem. 


esp err t esp wifi stop() 





This will stop the ESP32 WiFi subsystem. This could be called after a previous 
esp wifi start() Call. 


Includes: 
¢ #include <esp_wifi.h> 
See also: 


Starting up the WiFi environment 
esp_wifi_start 


WiFi WPS 


wifi_wps_enable 
bool wifi_wps enable(WPS TYPE t wps_type) 





The type parameter can be one of the following: 


* WPS TYPE DISABLE — Unsupported 








* wPS TYPE PBc — Push Button Configuration — Supported 


* WPS TYPE prin — Unsupported 


* WPS TYPE DISPLAY — Unsupported 

















* WPS TYPE Max — Unsupported 


See also: 


. WiFi Protected Setup — WPS 
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wifi_wps_disable 
bool wifi_wps disable () 


See also: 


° WiFi Protected Setup — WPS 


wifi_wps_start 
bool wifi_wps_ start () 


See also: 


. WiFi Protected Setup — WPS 


wifi_set_wps_cb 
bool wifi set wps cbh(wps st cb t callback) 





The signature of the callback function is: 


void (*functionName) (int status) 
The status parameter will be one of: 


* WPS CB ST SUCCESS — 





* WPS CB ST FAILED — 











¢ WPS CB ST TIMEOUT — 
See also: 


° WiFi Protected Setup — WPS 


mbed TLS 
The mbed TLS is an implementation of SSL/TLS security and is supplied with ESP-IDF. 


See also: 


TLS, SSL and security 
mbed TLS home page 
mbed TLS tutorial 





mbedtls_ctr_drbg_free 
mbedtls ctr _drbg free(mbedtls_ ctr_drbg_context *ctx) 


mbedtls_ctr_drbg_init 
void mbedtls_ ctr _drbg_ init(mbedtls_ctr_drbg context *ctx) 
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mbedtls_ctr_drbg_seed 
Initial seeding. 


int mbedtls_ ctr_drbg_seed( 
mbedtls_ctr_drbg_ context *ctx, 
int (*) (void *, unsigned char *, size t) £ entropy, 
void *p entropy, 
const unsigned char *custom, 
size t len) 


Includes: 
¢ mbed/ctr_drbg.h 


mbedtls_debug_set_threshold 
Set the debug level. 


void mbedtls debug _set_threshold(int threshold) 





Set the level of debugging to be generated from the library. The threshold value can be 
one of: 


* 0Q-no debug 
¢* 1 —error 
¢ 2-state change 
¢ 3- informational 
¢ 4 -verbose 
A higher level captures that level and the entries of lower level. 


Note: To use this function, mbedTLS debugging must be enabled by editing the Curl 
mbeditls.c. 


Includes: 
¢ mbedtls/debug.h 


See also: 


mbedtls_ssl_conf_dbg 
mbedtls_strerror 


mbedtls_entropy_free 
void mbedtls entropy free(mbedtls entropy context *ctx) 


Includes: 
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* mbed/entropy.h 


mbedtls_entropy_init 
void mbedtls entropy init (mbedtls_ entropy context *ctx) 


Includes: 


* mbed/entropy.h 


mbedtls_net_accept 

int mbedtls_net_accept ( 
mbedtls net context *bind_ctx, 
mbedtls net context *client ctx, 
void *client_ip, 











size t buf_size, 
size_t *ip len) 


mbedtls_net_bind 

int mbedtls_ net _bind( 
mbedtls net context *ctx, 
const char *bind_ip, 





const char *port, 
int proto) 


























The proto is one of MBEDTLS_NET PROTO TCP Of MBEDTLS NET PROTO UDP. 


mbedtls_net_connect 
Initiate a network connection. 





int mbedtls_net_ connect ( 
mbedtls net context *context, 





const char *host, 

const char *port, 

int proto) 
The context is the network context to use, host is the host to connect to, port is the 
port number (as a string) and proto is one Of MBEDTLS NET PROTO TCP Or 
MBEDTLS NET PROTO UDP. 




















Includes: 
* mbed/net.h 


See also: 


mbedtls_net_init 


mbedtls_net_free 
Gracefully shutdown the connection and release data. 
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void mbedtls net _free(mbedtls net_context *context) 





Release any resources associated with the context. Acall to mbedtls_ net _init() will 


have been called prior to this release call. 


See also: 


mbedtls_net_init 


mbedtls_net_init 
Initialize a context for use. 


void mbedtls net_init(mbedtls net context *context) 





Invoke this function early to initialize the context. Don't try and use a context before 


calling this function. 
Includes: 
¢ mbed/net.h 


See also: 


mbedtls_net_free 


mbedtls_net_recv 
Read data from a socket. 


int mbedtls_ net _recv( 
void *ctx, 
unsigned char *buf, 
size t len 


) 


mbedtls_net_recv_timeout 
int mbedtls_ net _recv_timeout ( 





void *ctx, 

unsigned char *buf, 
size t len, 
uint32 t timeout 


) 


mbedtls_net_send 
Send data down a socket. 


int mbedtls_ net _send( 
void *ctx, 
const unsigned char *buf, 
size t len) 
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mbedtls_net_set_block 
int mbedtls net _set_block(mbedtls net context *ctx) 





mbedtls_net_set_nonblock 
int mbedtls net _set_nonblock(mbedtls_ net context *ctx) 





mbedtls_printf 
Printf macro. 


Includes: 


¢ mbed/platform.h 


mbedtls_shat1 
Produce a 160bit (20 byte) hash value. 


void mbedtls_shal(const unsigned char *input, size t ilen, unsigned char output[20]) 
The input is the pointer to the data to be hashed. The i1en is the length of the input. 
The output is the resulting hash. 
Includes: 

* mbedtis/sha1.h 


mbedtls_ssl_close_notify 


mbedtls_ssl_conf_authmode 
Set the certificate verification mode. 


void mbedtls_ssl_conf_authmode ( 
mbedtls_ssl_ config *sslConf, 
int authmode) 


The ssiconf is the SSL configuration. The authmode is one of: 





* MBEDTLS SSL VERIFY NONE — 








* MBEDTLS SSL VERIFY OPTIONAL — 






































* MBEDTLS SSL VERIFY REQUIRED — 
Includes: 
* mbed/ssl.h 
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mbedtls_ssl_conf_ca_chain 


mbedtls_ssl_conf_dbg 
Set the debug callback. 


void mbedtls_ssl_conf_dbg( 
mbedtls_ssl_ config *conf, 
void(*func) (void *debugContext, 
void *debugContext) 


int level, 


char *file, 


int line, const char *str), 


An example of a function that can be used to log data might be: 


static void my _ debug ( 
void *ctx, 
int level, 
const char *file, 

int line, 

const char *str) { 

((void) level); 

((void) ctx); 

printf ("%s:%04d: Ss", file, 


line, str); 


} 
See also: 


. mbedtls_debug_set_threshold 
. mbedtls_strerror 


mbedtls_ssl_conf_rng 
Set the random number generator callback. 


void mbedtls_ssl_conf_rng( 
mbedtls_ssl_ config conf, 
int (*) (void *, 
void *p rng) 


unsigned char *, size t) f rng, 


Includes: 
* mbed/ssl.h 


mbedtls_ssl_config_defaults 
int mbedtls_ssl config defaults ( 
mbedtls_ssl_ config *sslConfig, 
int endpoint, 
int transport, 
int preset) 














The endpoint is one of MBEDT 

















The transport is MBEDTLS SS 


La 




















iS SSL_IS CLIENT OF MB! 


, TRANSPORT STREAM OF MB 





DTLS_SSL_IS_ SERVER. 








EDTLS SSL TRANSPORT DATAGRAM. 
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The preset is currently not used. Supply MBEDTLS SSL_PRESE 














E FAULT. 





Includes: 
* mbed/ssl.h 


mbedtls_ssl_config_free 
Release the resources for an SSL configuration context. 


void mbedtls_ssl config free(mbedtls_ssl_ config *sslConf) 
Includes: 
* mbed/ssl.h 


See also: 


mbedtls_ssl_config_init 


mbedtls_ssl_config_init 
Initialize an SSL Config record. 


void mbedtls_ssl config init (mbedtls_ssl_ config *sslConf) 
Includes: 
* mbed/ssl.h 


See also: 


mbedtls_ssl_config_free 


mbedtls_ssl_free 
Release resources for an SSL context. 


void mbedtls_ssl free(mbedtls_ssl_ context *sslContext) 


Release any resources that may have been previously allocated by a call to 


mbedtls_ ssl init(). 
Includes: 
* mbed/ssl.h 


See also: 


mbedtls_ssl_init 
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mbedtls_ssl_get_verify_result 
mbedtls_ssl_handshake 


mbedtls_ssl_init 
Initialze an SSL context. 


void mbedtls_ssl_init(mbedtls_ssl_context *sslContext) 
The data structure is a black box and this function initializes it for us. 
Includes: 

¢ mbed/ssl.h 


See also: 


mbedtls_ssl_free 


mbedtls_ssl_read 

int mbedtls_ssl_ read ( 
mbedtls_ssl_ context *sslContext, 
unsigned char *buf, 
size t len) 


mbedtls_ssl_session_reset 


mbedtls_ssl_set_bio 
Identify the functions to be used for sending and receiving data. 


void mbedtls_ssl_ set_bio( 
mbedtls_ssl context *context, 
void *p bio, 
mbedtls_ssl_send_t *f send, 
mbedtls ssl recv t *f recv, 








mbedtls_ssl_recv_timeout_t *f recv_timeout) 


The context is the SSL context we are currently using for this communication. 


The p_bio is a pointer to storage that is passed into the send and receive functions to 
give them context. 


The £_send is a function to be called to transmit SSL encrypted data. It can be 
mbedtls net send. The signature for this function is: 


int functionName (void *ctx, const unsigned char *buf, size t len) 


The £_recv is a function to be called to receive SSL encrypted data. It can be 
mbedtls net _recv. The signature for this function is: 
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int functionName (void *ctx, unsigned char *buf, size t len) 
The £ recv_timeout is a function to be called to receive SSL encrypted data with a 
timeout. It can be nuLL. The signature of this function is: 


int functionName (void *ctx, unsigned char *buf, size t len, uint32_t timeout) 


mbedtls_ssl_set_hostname 
Set the hostname to check against. 


int mbedtls_ssl_set_hostname ( 
mbedtls_ssl_ context *context, 
const char *hostname) 


Returns 0 on success. 
Includes: 
* mbed/ssl.h 


mbedtls_ssl_setup 
Setup an SSL context for use. 


int mbedtls_ssl_ setup( 
mbedtls_ssl_ context *sslContext, 
mbedtls_ssl_ config *sslConfig) 


Includes: 
* mbed/ssl.h 


mbedtls_ssl_write 
Write a buffer of data down the socket. 


int mbedtls_ssl write ( 
mbedtls_ssl_ context *ssl, 
const unsigned char *buf, 
size_t len) 


The number of bytes written or < 0 on error. 
Includes: 
¢ mbed/ssl.h 


mbedtls_strerror 
void mbedtls_strerror ( 
int errnum, 
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char *buffer, 
size_t bufflen) 


Convert an error code into a C string representing the error. 
Includes: 
¢ mbed/error.h 


See also: 


mbedtls_debug_set_threshold 
mbedtls_ssl_conf_dbg 


mbedtls_x509_crt_init 
Initialize a certificate chain. 


void mbedtls x509 crt_init(mbedtls_ x509 crt *crt) 
mbedtls_x509_crt_parse 


mbedtls_x509_crt_veryify_info 


Bluetooth LE 
See also: 


Bluetooth 


esp_bt_uuid_t 
A representation of a UUID. 


* uintl6e t len— The length of the UUID 


© ESP _UUID LEN 16 — 16 bits in length. 








© ESP_UUID LEN 32 — 32 bits in length. 














© ESP_UUID LEN 128 — 128 bits in length. 





* union uuid 


© uintl6 t uuid1é — Data for a 16 bit uuid. 





© uuid32 t uuid32 — Data for a 32 bit uuid. 


© uint8 t uuidl28[ESP_UUID LEN 128] — Data for a 128 bit uuid. 
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esp_gatt_id_t 
The description of a characteristic. 


This data type describes a characteristic. 
* esp _bt_uuid_t uuid 
¢ uint8_tinst_id 


esp_gatt_srvc_id_t 
The description of a service. 


* esp _gatt_id_tid 


¢ bool is_primary 


esp_ble_gap_config_adv_data 
Specify the data that we wish to advertise. 





sp err t esp ble gap config adv data(esp ble adv data t *adv_ data) 








The adv_data is a structure including: 

* bool set_scan_rsp 

* bool include_name 

¢ bool include_txpower 

¢ int min_interval 

¢ int max_interval 

¢ int appearance 

¢ uint16_t manufacturer_len 

¢ uint8_t*p_manufacturer_data 

¢ uint16_tservice_data_len 

¢ uint8 t*p service data 

* uint16_tservice_uuid_len 

¢ uint8 t*p_service_uuid 

¢ uint8_t flag — The flag is a boolean or of the following: 
o ESP_BLE_ADV_FLAG _LIMIT_DISC 
o ESP_BLE_ADV_FLAG_GEN_DISC 
o ESP_BLE_ADV_FLAG_BREDR_NOT_SPT 
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o ESP_BLE_ADV_FLAG_DMT_CONTROLLER_ST 
o ESP_BLE_ADV_FLAG_DMT_HOST_SPT 
o ESP_BLE_ADV_FLAG_NON LIMIT_DISC 


An example structure might be: 


static esp ble adv data t adv data; 
































adv_data.set_scan_rsp = false; 
adv_data.include_ name = true; 
adv_data.include_txpower = true; 
adv_data.min_interval = 0x20; 
adv_data.max_interval = 0x40; 
adv_data.appearance = 0x00; 
adv_data.manufacturer len = 07 

adv_data.p manufacturer data = NULL; 
adv_data.service data_len =07 

adv_data.p service data = NULL; 
adv_data.service uuid_len = 5327 

adv_data.p service uuid = test_service uuidl128; 
adv_data.flag = (ESP BLE ADV FLAG GEN DISC | 





ESP BLE ADV FLAG BREDR NOT SPT); 

















Includes: 
¢ #include <esp_gap_ble_api.h> 
See also: 


Performing advertising 
esp_ble_gap_start_advertising 
esp_ble_gap_stop_advertising 


esp_ble_gap_config_adv_data_raw 
esp_ble_gap_config_scan_rsp_data_raw 


esp_ble_gap_config_local_privacy 
sp_err t esp ble gap config local privacy(bool privacy enable) 








Includes: 


¢ #include <esp_gap_ble_api.h> 


esp_ble_gap_register_callback 
Register a callback for gap events. 





sp_err t esp ble gap register callback(esp profile cb _t callback) 





The esp profile cb t is aC function with the following signature: 
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void func(esp gap ble cb event t event, esp ble gap cb param t *param) 











The param is an an instance of a pointer to an esp ble gap cb param t. This is a union 
of structures. These are: 





¢ struct ble_adv_data_cmpl_evt_param adv_data_cmpl 
¢ struct ble _sca_rsp_data_cmpl_evt_param scan_rsp_data_cmpl 
¢ struct ble_scan_param_cmpl_evt_param scan_param_cmpl 
¢ struct ble _scan_result_evt_param scan_rst 
¢ struct ble_adv_data_raw_cmpl_evt_param adv_data_raw_cmpl 
¢ struct ble_adv_start_cmpl_evt_param adv_start_cmpl 
¢ struct ble_scan_start_cmpl_evt_param scan_start_cmpl 
* esp_ble_sec_t ble security 
°o esp_ble_sec_key_notif_t key_notif 
© esp _ble_sec_req tble_req 
°o esp_ble_key_t ble_key 
o esp_ble_local_id_keys_tble_id_keys 
° esp_ble_auth_cmpl_t auth_cmpl 
¢ struct ble _scan_stop_cmpl_evt_param scan_stop_cmpl 
¢ struct ble_adv_stop_cmpl_evt_param adv_stop_cmpl 
Event types include: 


ESP_GAP_BLE_ADV_ DATA SET COMPLETE _EVT 
* ESP _GAP BLE ADV DATA SET COMPLETE EVT — Called when advertizing data set is 
complete. Structure parameter is called scan rsp data_cmpl. 
































° esp _bt_status_t status 


ESP GAP BLE SCAN PARAM SET COMPLETE EVT 
* ESP GAP BLE SCAN PARAM SET COMPLETE EVT — Called when scan parameters set 
complete. Structure parameter is called scan param _cmpl. 
































° esp _bt_status_t status 


ESP_GAP_BLE_ SCAN RESULT _EVT 
* ESP GAP BLE SCAN RESULT EvT — The param is an instance of 


esp ble gap cb param t. Called when one scan result is ready. Structure 
parameter is called scan rst. 
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esp gap search evt_t search evt — Choices are 











=™ ESP GAP SEARCH INQ RES EVT — We have received a search result. 














=™ ESP GAP SEARCH INQ CMPL EvT — The search is complete. 
# ESP_GAP_SEARCH_DISC_RES_EVT 

=» ESP_GAP_SEARCH_DISC_BLE_RES_EVT 

=» ESP_GAP_SEARCH_DISC_CMPL_EVT 

# ESP_GAP_SEARCH_DI_DISC_CMPL_EVT 

=» ESP_GAP_SEARCH_ SEARCH _CANCEL_CMPL_EVT 
esp bd addr t bda— The address of the device. 6 bytes of data. 
esp bt dev type t dev type — One of: 

» ESP_BT_DEVICE_TYPE_BREDR 

» ESP_BT_DEVICE_TYPE_BLE 

# ESP_BT_DEVICE_TYPE_DUMO 








esp ble addr type t ble addr type — One of 
» BLE ADDR_TYPE_PUBLIC 

» BLE ADDR_TYPE_RANDOM 

» BLE _ADDR_TYPE_RPA_PUBLIC 

» BLE _ADDR_TYPE_RPA_RANDOM 





esp ble evt type t ble evt type —Oneof 

» ESP_BLE_EVT_CONN_ADV 

» ESP_BLE_EVT_CONN_DIR_ADV 

» ESP_BLE_EVT_DISC_ADV 

» ESP_BLE_EVT_NON_CONN_ADV 

» ESP_BLE_EVT_SCAN_RSP 

int rssi — The signal strength. 

uint8_t ble_adv[ESP_BLE_ADV_DATA_LEN_MAX] 
int flag 





int num_resps 


Page 521 


ESP GAP 





BI 





1K SCAN RSP DATA SI 











ET COMPL 








ET EB 





EVT — Called when the scan 











response data set is complete. Structure parameter is called 


scan_rsp data_cmpl. 


° esp _bt_status_t status 


ESP_GAP BLE SCAN RSP DATA SET COMPLETE EVT 





ESP_GAP_BLE_AUTH_CMPL_EVT 





On receipt, the param field called ble security is populated which is itself a union. The 
field called auth _cmp1 within it is populated: 


esp_bd_addr_t bd_addr 


bool key_present 


esp_link_key key 


uint8_t key_type 


bool success 


uint8_t fail_ reason 


esp_bd_addr_type_t addr_type 


esp_bt_dev_type_t dev_type 


ESP_GAP BLE KEY EVT 


ESP_GAP BLE SEC REQ EVT 


ESP_GAP BLE PASSKEY NOTIF EVT 





ESP_GAP BLE PASSKEY REQ EVT 


ESP_GAP_BLE_OOB_REQ EVT 





ESP_GAP_BLE_ LOCAL _IR_EVT 





ESP_GAP BLE LOCAL ER EVT 


ESP_GAP_BLE_NC REQ EVT 





ESP_GAP BLE ADV STOP COMPLETE EVT 


ESP GAP BLE SCAN STOP COMPLETE EVT 
Includes: 


#include <esp_gap_ble_api.h> 


See also: 
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Performing a scan 
esp_ble_gap_start_scanning 


esp_ble_gap_set_device_name 
sp err t esp ble gap set device name(const char *name) 








Includes: 


¢ #include <esp_gap_ble_api.h> 


esp_ble_gap_set_scan_params 
Set the parameters for a subsequent BLE scan. 


sp_err t esp ble gap _set_scan_params(esp ble scan _params _t *scan_ params) 











* esp ble scan type t scan type — Scan type. One of: 











© BLE SCAN TYPE PASSIVE — Perform a passive scan where no scan response is 
requested from the advertizer. 














© BLE SCAN TYPE ACTIVE — Perform an active scan where a scan response is 
requested from the advertizer. 








* esp ble addr type t own addr type — Own address type. One of: 
o BLE ADDR_TYPE_PUBLIC 
o BLE ADDR_TYPE_RANDOM 
o BLE _ADDR_TYPE_RPA_PUBLIC 
o BLE _ADDR_TYPE_RPA_RANDOM 





* esp ble scan filter t scan filter policy -— Filter policy. One of: 
o BLE _SCAN_FILTER_ALLOW_ALL 
o BLE _SCAN_FILTER_ALLOW_ONLY_WLST 
o BLE _SCAN_FILTER_ALLOW_UND_RPA_DIR 
o BLE _SCAN_FILTER_ALLOW_WLIST_PRA_DIR 


* uintl6_t scan interval — Interval between scans. Value is multiplied by 0.625 
msecs. 








* uint16 t scan window — Duration of the scan. Must be less than or equal to the 
scan_interval. 
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Includes: 
¢ #include <esp_gap_ble_api.h> 
See also: 


esp_ble_resolve_adv_data 
esp_ble_gap_start_scanning 
esp_ble_gap_stop_scanning 


esp_ble_gap_set_pkt_data_len 

sp err t esp ble gap set pkt data len ( 
esp bd_addr_t remote device, 
uint1l6 t tx _data_length) 








Includes: 


¢ #include <esp_gap_ble_api.h> 


esp_ble_gap_set_rand_addr 
sp err t esp ble gap set rand addr(esp bd addr t rand addr) 











Includes: 


¢ #include <esp_gap_ble_api.h> 


esp_ble_gap_start_advertising 
Start GAP protocol advertizing. 





sp err t esp ble gap start advertising(esp ble adv params t *adv params) 








We can stop GAP protocol advertizing by calling esp ble gap stop advertising(). 





The adv_params Structure contains the following: 
* uint16_t adv_int_min 
¢ uint16_t adv_int_max 
* esp ble adv type t adv type — One of: 
° ADV_TYPE_IND 
o ADV_TYPE_DIRECT_IND_HIGH 
o ADV_TYPE_NONCONN_IND 
o ADV_TYPE_DIRECT_IND_LOW 





* esp ble addr type t own addr type — One of 
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= BLE_ADDR_TYPE_PUBLIC 

= BLE_ADDR_TYPE_RANDOM 

= BLE_ADDR_TYPE_RPA_PUBLIC 
= BLE_ADDR_TYPE_RPA_RANDOM 


* esp bd addr _t peer_addr 


* esp ble addr type t peer addr type —One of 


(e) 


(e) 


(e) 


(e) 





BLE_ADDR_TYPE_PUBLIC 
BLE_ADDR_TYPE_RANDOM 
BLE_ADDR_TYPE_RPA_PUBLIC 
BLE_ADDR_TYPE_RPA_RANDOM 


° esp ble adv_channel t channel map — One of: 


(e) 


(e) 


(e) 


(e) 


ADV_CHNL_37 
ADV_CHNL_38 
ADV_CHNL_39 
ADV_CHNL_ALL 


* esp ble adv filter t adv filter policy — One of: 


(e) 


(e) 


(e) 


(e) 


ADV_FILTER_ALLOW_SCAN_ANY_CON_ANY 
ADV_FILTER_ALLOW_SCAN_WLST_CON_ANY 
ADV_FILTER_ALLOW_SCAN_ANY_CON_WLST 
ADV_FILTER_ALLOW_SCAN_WLST_CON_WLST 


An example structure might be: 


esp ble adv params t adv params; 





adv_params. 
adv_params. 
adv_params. 


adv_params 


adv_params. 
adv_params. 


Includes: 


adv_int_min 0x20; 

0x40; 

ADV_TYPE_ IND; 

BLE _ADDR_TYPE PUBLIC; 

ADV_CHNL_ ALL; 

ADV FILTER ALLOW SCAN ANY CON ANY; 


adv_int_max 
adv_type 
-own_addr_type 











channel map 


adv_filter policy 








¢ #include <esp_gap_ble_api.h> 


See also: 
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Performing advertising 

esp_ble_gap_stop_advertising 
esp_ble_gap_config_adv_data 
esp_ble_gap_register_callback 


esp_ble_gap_start_scanning 
Start scanning for arriving advertising packets. 





sp_err t esp ble gap start _scanning(uint32 t duration) 





The duration is how long we are to perform scanning measured in seconds. 
Includes: 

¢ #include <esp_gap_ble_api.h> 
See also: 


esp_ble_gap_set_scan_params 
esp_ble_gap_stop_scanning 


esp_ble_gap_stop_advertising 
Stop advertising. 





sp err t esp ble gap stop advertising (void) 





Includes: 


¢ #include <esp_gap_ble_api.h> 


esp_ble_gap_stop_scanning 
Stop the current in progress scanning looking for advertising packets. 


sp err t esp ble gap stop scanning (void) 








Includes: 
¢ #include <esp_gap_ble_api.h> 
See also: 


esp_ble_gap_start_scanning 
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esp_ble_gap_update_conn_params 
sp err t esp ble gap update conn params(esp ble conn update params t *params) 











Includes: 


¢ #include <esp_gap_ble_api.h> 


esp_ble_gattc_app_register 
Register application callbacks. 





sp_err t esp ble gattc_app register(uintl6 t app id) 





The app_idis the identity of an application. This can be any numeric smaller than 
Ox7FffF. 


Includes: 


¢ #include <esp_gattc_api.h> 


esp_ble_gattc_app_unregister 
sp err t esp ble gattc app unregister(esp gatt if t gatt if) 











Includes: 


¢ #include <esp_gattc_api.h> 


esp_ble_gattc_close 
Close a previously opened connection. 





sp_err t esp ble gattc_close(uintl6 t conn_id) 





Includes: 
¢ #include <esp_gattc_api.h> 
See also: 


esp_ble_gattc_open 


esp_ble_gattc_config_mtu 
sp_err t esp ble gattc_config mtu(uintl6 t conn_id, uint1l6 t mtu) 








Includes: 


¢ #include <esp_gattc_api.h> 
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esp_ble_gattc_execute_write 
sp err t esp ble gattc_execute write ( 








esp gattc_if t gattc_if, 
uintl6 t conn_id, 
bool is execute) 


Includes: 


¢ #include <esp_gattc_api.h> 


esp_ble_gattc_get_characteristic 
Ask the BLE partner to return a characteristic. 





sp err t esp ble gattc get characteristic ( 





esp gatt_if_t gattc_if, 
uintl6 t conn_id, 
esp gatt_srvc_id_t *srvc_id, 





esp gatt_id_t *start_ characteristic _id) 


When this call is made a request is sent to the GATT server to return the "next" 
characteristic. We should imagine that a GATT service has a set of 0 or more 
characteristics that it maintains in some form of internal order. The numeric order is not 
important, only that there is the concept of a "next" and "no more". When we call this 
function with start characteristic id set to NULL then we are saying "get me the first 
characteristic". If we subsequently call the function again passing in the id of the last 
characteristic returned, we will get the next characteristic. When we reach the end of 
the characteristics, the status code in the returned event will no longer be ok. 


This call is a request only and the response will come asynchronously as an 
ESP GATTC GET CHAR EVT event. 














The conn_id Is the identity of a connection to the server. 


The srvc_id is the identity of a service on the GATT server. This can be obtained by 
performing a search request against the server and the esp gatt_srvc id _t is returned 
iN aN ESP_GATTC_ SEARCH RES_EVT Callback. 























The start characteristic id can be NULL to get the first characteristic. 


Since we are iterating through characteristics, there must be a way to learn that there 
are no more. This is determined because we get a status of EsP_GATT ERROR for the 
ESP GATTC GET CHAR EvT event. 




















Includes: 
¢ #include <esp_gattc_api.h> 
See also: 


ESP_GATTC_SEARCH_RES_EVT 
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ESP_GATTC_GET_CHAR_EVT 


esp_ble_gattc_get_descriptor 
sp err t esp ble gattc get descriptor ( 
esp gatt_if_t gattc_if, 
uint1l6 t conn_id, 








esp gatt_srvc_id_t *srvc_id, 
esp gatt_id_t *characteristic id, 





esp gatt_id_t *start_descriptor_ id) 








The start descriptor id can be NULL to get the first descriptor. 


Includes: 


¢ #include <esp_gattc_api.h> 


esp_ble_gattc_get_included_service 
sp_err t esp ble gattc_get_included_service ( 
esp gatt_if_t gattc_if, 
uint1l6 t conn_id, 








esp gatt_srvc_id_t *srvc_id, 
esp gatt_srvc_id_t *start_incl srvc_id) 








Includes: 


¢ #include <esp_gattc_api.h> 


esp_ble_gattc_open 
Open a connection to the GATT server. 





sp err t esp ble gattc open ( 
esp gatt if t gatt if, 
esp_bd_addr_t remote _ bda, 
bool is direct) 








The gatt_if is the application identity. The initial is ESP GATT IF NONE. 








The remote _bda Is the bluetooth device address to which we wish to connect. 


If is direct then we are asking for a direct connection otherwise a background auto 


connection. 
Includes: 


¢ #include <esp_gattc_api.h> 
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See also: 


esp_ble_gattc_close 
ESP_GATTC_OPEN_EVT 
ESP_GATTC_CLOSE_EVT 


esp_ble_: 


gattc_prepare_write 





sp err t 


sp ble gattc_prepare write ( 





esp ga 


uintl6_ 


esp ga 


ttc if t gattc_if, 
t conn_id, 
tt_srvc_id_t *srvc_id, 





esp ga 
uintl16 


tt_id_ t *char_ id, 
t offset, 


uintl6_ 


uint8 | 
esp ga 


t value_len, 
t *value, 





tt auth req t auth req) 





Includes: 


¢ #include <esp_gattc_api.h> 


esp_ble_gattc_read_char 
Read a characteristic. 





sp err t 


sp ble gattc read char ( 





esp gatt_if_t gattc_if, 
uint16 t conn_id, 


esp gatt_srvc_id_t *srvc_id, 





esp gatt_id_t *characteristic_ id, 


esp gatt auth req t auth req) 





The auth req is one of: 
¢ ESP_GATT_AUTH_REQ NONE 
* ESP_GATT_AUTH_REQ NO MITM 
¢ ESP_GATT_AUTH_REQ_MITM 
¢ ESP_GATT_AUTH_REQ_ SIGNED NO _MITM 
¢ ESP_GATT_AUTH_REQ_SIGNED_MITM 


Includes: 


¢ #include <esp_gattc_api.h> 


See also: 


ESP_GATTC_READ_CHAR_EVT 
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esp_ble_gattc_read_char_descr 
sp err t esp ble gattc read char descr ( 

esp gatt_if_t gattc_if, 

uint1l6 t conn_id, 

esp gatt_srvc_id_t *srvc_id, 

esp gatt_id_t *char_id, 

esp gatt_id_t *descr_ id, 

esp gatt auth req t auth req) 














Includes: 


¢ #include <esp_gattc_api.h> 


esp_ble_gattc_register_callback 
Register a callback to be invoked when a GATT event is received. 





sp_err t esp ble gattc_register callback(esp gattc_cb _t callback) 





The esp gattc cb t is aC function definition for a function with the signature: 


void func ( 
esp gattc cb event t event, 
esp gatt_if_t gattc_if, 





esp ble gattc cb param t *param) 





Event types include: 
¢ ESP_GATTC_ACL_EVT 
« ESP_GATTC_ADV_DATA_EVT 
¢ ESP_GATTC_ADV_VSC_EVT 
* ESP_GATTC_BTH_SCAN_CFG_EVT 
* ESP_GATTC_BTH_SCAN_DIS_EVT 
¢ ESP_GATTC_BTH_SCAN_ENB EVT 
* ESP_GATTC_BTH_SCAN_PARAM_EVT 
* ESP_GATTC_BTH_SCAN_RD_EVT 
¢ ESP_GATTC_BTH_SCAN_THR_EVT 
* ESP_GATTC_CANCEL_OPEN_EVT 
¢ ESP_GATTC_CFG_MTU_EVT 

















* ESP GATTC CLOSE EvT—Invoked when a connection is closed. 
¢ ESP _GATTC_CONGEST_EVT 
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ESP_GATTC_ENC_CMPL_CB_EVT 
ESP_GATTC_EXEC_EVT 


ESP_GATTC GET CHAR EVT — Response to getting a characteristic. 





























ESP_GATTC GET _DESCR_EVT — Response to getting a characteristic description. 











ESP_GATTC_GET_INCL_SRVC_EVT 
ESP_GATTC_MULT_ADV_DATA_EVT 
ESP_GATTC_MULT_ADV_DIS_EVT 
ESP_GATTC_MULT_ADV_ENB_EVT 
ESP_GATTC_MULT_ADV_UPD_EVT 
ESP_GATTC_NOTIFY_EVT 





ESP_GATTC OPEN EvT — Invoked when a connection is opened. 

















ESP _GATTC PREP WRITE EvT — Response to write a characteristic. 

















ESP _GATTC READ CHAR EVT — Response to read a characteristic. 





























ESP_GATTC REG _EVT — Invoked when a GATT client has been registered. 


ESP_GATTC_REG_FOR_NOTIFY_EVT 
ESP_GATTC_SCAN_FLT_CFG_EVT 
ESP_GATTC_SCAN_FLT_PARAM_EVT 
ESP_GATTC_SCAN_FLT_STATUS_EVT 


ESP_GATTC SEARCH _CMPL_ EVT — Invoked when we have seen all search results. 























ESP_GATTC SEARCH RES _EVT — Invoked when we have a search result. 








ESP_GATTC_SRVC_CHG_EVT 
ESP_GATTC_READ_DESCR_EVT 
ESP_GATTC_UNREG_EVT 
ESP_GATTC_UNREG_FOR_NOTIFY_EVT 
ESP_GATTC_WRITE_CHAR_EVT 
ESP_GATTC_WRITE_DESCR_EVT 


The param is a data structure that provides further details on the event. It appears to be 
an instance of esp ble gattc cb param t which is a union of: 
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cfg mtu — set for ESP GATTC CFG MTU EVT. 





close — set for 1 





congest — 


exec _cmpl1 — set for } 


get_char — Set for 





ESP GATTC CLOSE 








EVT. 








ESP GATTC_ CONG 





t_descr — Set for | 








EST_ 





EVT. 








ESP GATTC GE 


ESP GATTC 


BX 





EC 





EVT. 











T CHAR EVT. 








ESP GATTC G 











ET DESCR 





EVT. 








get_incl srvc—setfor Esp GAT 





no 


open — set for Es 


tify — set for: 





read — set for Es 


reg — set for | 





reg for notify —Setfor esp GATTC_ REG FOR NOTIFY_ 


ESP GATTC_RE 


P GATTC OF 








TC GET INCL SRVC EVT. 








ESP GATTC NOTIFY _ 








PD 


EN 














P GATTC 





READ C 





EVT. 


EVT. 


HAR 








EVT and ESP GATTC RE 








iAD D 





ESCR 





EVT. 

















iG 








EVT. 





EVT. 








search cmpl — Set for ESP GaTTc 


search res — Set for} 
srvc_chg — Set for | 
unreg for notify — set for ESP 


write — set for 
ESP GATTC WRITE 








ESP GATTC W 


-, 
F 
ES 








ESP GATTC SEARCH _ 


P GATTC SRVC CHG 


SEARCH _CMPL_EVT. 




















RE 





EVT. 





iS. 


EVT. 








GATTC UNR 








RIT! 





= 
G 
aa 











CHAR EVT, 





iSP GATTC PRI 





EG FOR NOTIFY | 





EVT. 


EP WRITE 








EVT and 























D 





ESCR 








EVT. 








Includes: 


#include <esp_gattc_api.h> 


ESP_GATTC_CLOSE_EVT 








Now let us look more deeply at each event type. 


esp gatt status t status — Operation status. 


uint16 t conn id — Connection id. 


Published when a GATT client connection is closed. The close field of 
esp ble gattc cb param t iS populated. It contains: 


esp gatt if t gatt if — Gatt interface id, different application on gatt client 
different gatt_if. 
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esp bd addr _t remote bda — Remote bluetooth device address. 


esp gatt conn reason t reason — The reason of gatt connection close. One 
of: 


© ESP GATT CONN UNKNOWN — Gatt connection unknown. 


© ESP GATT CONN L2C_ FAILURE — General L2cap failure. 








© ESP GATT CONN TIMEOUT — Connection timeout. 





© ESP GATT CONN TERMINATE PEER _USER — Connection terminate by peer user. 


























© ESP GATT CONN TERMINATE LOCAL HOST — Connection terminated by local 
host. 














° ESP GATT CONN FAIL ESTABLISH — Connection fail to establish. 








© ESP GATT CONN LMP TIMEOUT — Connection fail for LMP response tout. 











° ESP GATT CONN CONN CANCEL —L2CAP connection canceled. 























© ESP GATT CONN NONE — No connection to cancel. 


ESP_GATTC_ GET CHAR _EVT 





Published when a GATT client open call has been made. The get char field of 
esp ble gattc cb param t IS populated. It contains: 
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esp gatt status t status — Operation status. On success, ESP GATT oK is 
returned. 


uint16 t conn _id— Connection id. 


esp gatt_srvc id t srvc_id— Service id, include service uuid and other 
information. 








esp gatt id _t char id— Characteristic id, include characteristic uuid and 
other information. If the status field indicates an error, this field should not be 
examined. 


© esp_bt_uuid_t uuid 
° uint8_t inst_id 


esp gatt char prop t char prop — Characteristic properties. This is the set of 
flags that identify what can be done against the characteristics. If the status 
field indicates an error, this field should not be examined. The bit flags are: 


o ESP_GATT_CHAR_PROP_BIT_AUTH 
o ESP_GATT_CHAR_PROP_BIT_BROADCAST 





o ESP_GATT_CHAR_PROP_BIT_EXT_PROP 
o ESP_GATT_CHAR_PROP_BIT_INDICATE 
o ESP_GATT_CHAR_PROP_BIT_NOTIFY 

o ESP_GATT_CHAR_PROP_BIT_READ 

o ESP_GATT_CHAR_PROP_BIT_WRITE 

o ESP_GATT_CHAR_PROP_BIT_WRITE_NR 


See also: 


esp_ble_gattc_get_characteristic 


ESP_GATTC OPEN _EVT 

Published when a GATT client open call has been made. This is normally the result of 
calling esp ble gattc_open(). The open field of esp ble gattc cb param t is 
populated. It contains: 








* esp gatt status t status — Operation status. The status should be checked to 
see what the outcome of the request may be. A good return is ESP_GATT OK. 





* uintl6 t conn _id—Connection id. 





* esp gatt if t gatt if —GATT interface id, different application on GATT client 
different gatt_if 





* esp bd addr t remote bda — Remote bluetooth device address. 
* uint16 t mtu—MTU size. 


See also: 


esp_ble_gattc_open 


ESP_GATTC READ CHAR EVT 
Published when a GATT characteristic value has been received. The read field of 
esp ble gattc cb param t IS populated. It contains: 








* esp gatt status t status — Operation status. 
* uint16 t conn_id— Connection id. 


* esp gatt srvc id t srvc id— Service id, include service uuid and other 
information. 
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* esp gatt id t char id— Characteristic id, include characteristic uuid and 
other information. 


* esp gatt id t descr id— Descriptor id, include descriptor uuid and other 
information. 





* uint8 t *value — Characteristic value. 





* uintl6 t value_type — Characteristic value type. By experimentation we seem 
to find: 


° Q-string 
* uint16 t value _len— Characteristic value length. 


See also: 


esp_ble_gattc_read_char 


ESP_GATTC_ REG EVT 
Published when a GATT client has been registered. The reg field of 
esp ble gattc cb param t iS populated. It contains: 








* esp gatt status t status — Operation status. A GATT status code. 














* esp gatt if t gatt if —GATT interface id, different application on gatt client 
different gatt_if. 





* uint16 t app ia—Application id which input in register API. 


ESP_GATTC_ SEARCH CMPL_EVT 

Published when all search results has been received following a call to 

esp ble gattc_ search service(). The search cmpl field of esp ble gattc_ cb param t 
is populated. It contains: 








* esp gatt status t status — Operation status. 
* uint16 t conn id — Connection id. 


See also: 


esp_ble_gattc_search_service 
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ESP_GATTC SEARCH RES EVT 

Published a search result has been received following a call to 

esp ble gattc_ search service(). The search_res field of esp ble gattc_cb param t 
is populated. This is an instance of struct gattc_ search res evt param. It contains: 








* uintl6 t conn_id—Connection id. 





* esp gatt srvc id t srvc _id— Service id, includes service uuid and other 
information. Specifically: 





° esp gatt id t id—The details of the GATT id. This contains: 
= esp bt uuid t uuid— The UUID of the service. 
* uintl6 t len—The length of the UUID. Can be one of: 


© ESP UUID LEN 16 — 16 bit length. 





© ESP _UUID LEN 32 — 32 bit length. 




















© ESP UUID LEN 128 — 128 bit length. 

* union uuid—Aunion of the possible UUID value types 
© uint16 t uvida1é — 16 bit UUID. 
© uint32 t uuid32 — 32 bit UUID. 








© uint8 t uuidl28[ESP_UUID LEN 128] — 128 bit UUID. 








= uint8 t inst _id— The instance of the service. 
© bool is primary -—Is this a primary service. 


See also: 


esp_ble_gattc_search_service 
esp_ble_gattc_get_characteristic 


esp_ble_gattc_register_for_notify 
esp gatt_status_t esp ble gattc_register for notify ( 

















esp gatt_if t gatt_if, 

esp bd addr t server hbda, 

esp gatt_srvc id t *srvc_id, 

esp gatt_id t *char_ id) 
Includes: 


¢ #include <esp_gattc_api.h> 
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esp_ble_gattc_unregister_for_notify 
esp gatt_status_t esp ble gattc_unregister for notify (esp gatt_if t gatt_if, 
esp_bd_addr_t server hbda, 








esp gatt_srvc_id_t *srvc_id, 
esp gatt_id_ t *char_id); 





Includes: 


¢ #include <esp_gattc_api.h> 


esp_ble_gattc_search_service 
Ask the BLE device for the services it provides. The services will be returned 
asynchronously via GATT events. 





sp err t esp ble gattc search service ( 
esp gatt_if_t gattc_if, 
uintl6 t conn_id, 
esp bt_uuid_t *filter uuid) 





The gattc_if is returned to us in the open event callback. 


The conn_id Is the identity of a connection that was opened by a call to 
esp ble gattc_open() and obtained from a GATT event callback. 


The filter uuid allows us to filter UUIDs or else we can specify NuLL. 


After calling this function we might expect to see a sequence of 
ESP_GATTC SEARCH RES EvT events published finalized with an 
ESP _GATTC SEARCH CMPL EVT. 





























Includes: 
¢ #include <esp_gattc_api.h> 
See also: 


ESP_GATTC_SEARCH_CMPL_EVT 
ESP_GATTC_SEARCH_RES_EVT 


esp_ble_gattc_write_char 
sp err t esp ble gattc write char ( 
esp gatt_if_t gattc_if, 
uint16 t conn_id, 








esp gatt_srvc_id_t *srvc_id, 





esp gatt_id_t *characteristic id, 
uintl6 t value len, 

uint8 t *value, 

esp gatt_write type t write type, 
esp gatt auth req t auth req) 














Includes: 
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¢ #include <esp_gattc_api.h> 


esp_ble_gattc_write_char_descr 





sp err t esp ble gattc write char descr ( 





esp gatt_if_t gattc_if, 
uint16 t conn_id, 
esp gatt_srvc_id_t *srvc_id, 





esp gatt_id_t *char_id, 

esp gatt_id_t *descr_ id, 

uintl6 t value _len, 

uint8 t *value, 

esp gatt_write type t write type, 
esp gatt auth req t auth req) 














Includes: 


¢ #include <esp_gattc_api.h> 


esp_ble_gatts_add_char 
sp err t esp ble gatts add char ( 
uintl6 t service handle, 








esp bt_uuid_t *char_uuid, 


esp _gatt_perm_t perm, esp gatt_char_ prop t property, 





esp_attr_value t *char val, 
esp_attr_ control t *control) 


Includes: 


¢ #include <esp_gatts_api.h> 


esp_ble_gatts_add_char_descr 
sp err t esp ble gatts add char descr ( 
uintl6 t service handle, 








esp bt_uuid_t *descr_uuid, 

esp _gatt_perm_t perm, 
esp_attr_value t *char descr val, 
esp_attr_ control t *control) 


Includes: 


¢ #include <esp_gatts_api.h> 


esp_ble_gatts_add_included_service 





sp_err t esp ble gatts_add_included_service(uintl6 t service handle, uintl6 t 





included_service_handle) 
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Includes: 


¢ #include <esp_gatts_api.h> 


esp_ble_gatts_app_register 
sp_err t esp ble gatts_app register(uintl6 t app _ id) 








The app_idis the identity of an application. This can be any numeric smaller than 
Ox7FffF. 


Includes: 


¢ #include <esp_gatts_api.h> 


esp_ble_gatts_app_unregister 
sp_err t esp ble gatts_app _unregister(esp gatt_if_ t gatts_if) 








Includes: 


¢ #include <esp_gatts_api.h> 


esp_ble_gatts_close 
sp err t esp ble gatts close( 
esp gatt_if_t gatts if, 
uintl6 t conn_id) 








Includes: 


¢ #include <esp_gatts_api.h> 


esp_ble_gatts_create_attribute_tab 
sp err t esp ble gatts create attr tab( 
const esp gatts_attr_db t *gatts_attr_db, 
esp gatt_if_t gatts if, 
uint8 t max_nb attr, 











uint8 t srvc_inst_id) 
Includes: 


¢ #include <esp_gatts_api.h> 


esp_ble_gatts_create_service 
Create a service definition. 





sp err t esp ble gatts create service ( 





esp gatt_if_t gatts if, 


Page 540 


esp gatt_srvc_id_t *service id, 
uintl6 t num_handle) 





The service_id is a structure containing: 
* esp _gatt_id_tid 


* bool is_primary 


The num_handle is the number of the handle requested for this service. 


Includes: 


¢ #include <esp_gatts_api.h> 


esp_ble_gatts_delete_service 
sp_err t esp ble gatts_ delete service(uintl6 t service handle); 








Includes: 


¢ #include <esp_gatts_api.h> 


esp_ble_gatts_get_attr_value 
sp err t esp ble gatts get attr value ( 
uintl6 t attr_handle, 
uintl6 t *length, 
const uint8 t **value) 








Includes: 


¢ #include <esp_gatts_api.h> 


esp_ble_gatts_open 
sp err t esp ble gatts open ( 
esp gatt_if_t gatts if, 
esp_bd_addr_t remote _ bda, 
bool is direct) 








Includes: 


¢ #include <esp_gatts_api.h> 


esp_ble_gatts_register_callback 
Register GATT server callbacks. 
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sp_err t esp ble gatts_ register callback(esp gatts_cb _t callback) 





The callback is an instance of a callback function that has the following signature: 


void callback ( 
esp gatts cb event t event, 
esp gatt_if_t gatts if, 





esp ble gatts cb param t *param 


) 





The esp ble gatts cb param t is a union of: 





¢ struct gatts_add_attr_tab_evt_param add_attr_tab 
¢ struct gatts_add_char_evt_param add_char 

¢ struct gatts_add_char_descr_evt_param add_char_descr 
¢ struct gatts_conf_evt_param conf 

* struct gatts_connect_evt_param connect 

¢ struct gatts_create_evt_param create 

¢ struct gatts_delete_evt_param del 

¢ struct gatts_disconnect_evt_param disconnect 

¢ struct gatts_exec_write_evt_param exec_write 

¢ struct gatts_mtu_evt_param mtu 

¢ struct gatts_read_evt_param read 

¢ struct gatts_reg_evt_param reg 

¢ struct gatts rsp evt_param rsp 

¢ struct gatts_set_attr_val_evt_param set_attr_val 

¢ struct gatts_start_evt_param start 

* struct gatts_stop_evt_param stop 


¢ struct gatts_write_evt_param write 


The event is one of: 


ESP GATTS REG EVT 
Invoked when ?7?. 





The passed in parameter is an instance of struct gatts reg _evt_ param which is 
identified by the field called reg. The structure contains: 


* esp gatt_status t status 
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« uint16 tapp_id 


ESP_GATTS READ EVT 

When a GATT client connects, we receive this event. The passed in parameter is an 
instance of struct gatts read _evt_param which is identified by the field called reaa. 
The structure contains: 





¢ uint16_tconn_id 

* uint32_ttrans_id 

* esp bd addr _tbda 
¢ uint16_t handle 

* uint16_t offset 

* bool is_long 

* bool_need_rsp 


ESP_GATTS_ WRITE_EVT 





ESP_GATTS EXEC WRITE EVT 
ESP_GATTS MTU_EVT 





ESP_GATTS CONF _EVT 





ESP_GATTS UNREG EVT 


ESP_GATTS CREATE _EVT 
The passed in parameter is an instance of struct gatts_ create _evt_param which is 
identified by the field called create. The structure contains: 





* esp _gatt_status_t status 
¢ uint16_tservice_handle 


* esp_gatt_srvc_id_t service_id 


ESP_GATTS ADD INCL SRVC EVT 


ESP_GATTS ADD CHAR EVT 

When a GATT client connects, we receive this event. The passed in parameter is an 
instance of struct gatts add char evt param which is identified by the field called 
add_char. The structure contains: 
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* esp _gatt_status_t status 
¢ uint16 t attr_handle 
¢ uint16_tservice_handle 


* esp _bt_uuid_t char_uuid 


ESP_GATTS ADD CHAR DESC EVT 
ESP_GATTS DELETE EVT 


ESP_GATTS START EVT 

When a GATT client connects, we receive this event. The passed in parameter is an 
instance of struct gatts_ start _evt_param which is identified by the field called start. 
The structure contains: 


* esp gatt_status t status 


¢ uint16_tservice_handle 


ESP_GATTS STOP_EVT 





ESP_GATTS CONNECT EVT 

When a GATT client connects, we receive this event. The passed in parameter is an 
instance of struct gatts_ connect _evt_param which is identified by the field called 
connect. The structure contains: 





¢ uint16_tconn_id 
* esp bd addr _tremote_bda 


¢ bool is_connected 


ESP_GATTS DISCONNECT EVT 

When a GATT client connects, we receive this event. The passed in parameter is an 
instance of struct gatts disconnect _evt_ param which is identified by the field called 
disconnect. The structure contains: 


¢ uint16_tconn_id 
* esp bd addr _tremote_bda 


* bool is_connected 
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ESP_GATTS OPEN EVT 





ESP_GATTS CANCEL OPEN EVT 
ESP_GATTS CLOSE _EVT 





ESP_GATTS LISTEN _EVT 





ESP_GATTS CONGEST EVT 
ESP_GATTS_RESPONSE_EVT 





ESP_GATTS CREAT ATTR TAB EVT 
ESP_GATTS SET ATTR VAL EVT 


Includes: 


¢ #include <esp_gatts_api.h> 


esp_ble_gatts_send_indicate 
sp err t esp ble gatts send indicate ( 

esp gatt_if_t gatts if, 
uint16 t conn_id, 
uintl6 t attr_handle, 
uintl6 t value _len, 
uint8 t *value, 
bool need_confirm) ; 








Includes: 


¢ #include <esp_gatts_api.h> 


esp_ble_gatts_send_response 
sp err t esp ble gatts send response ( 
esp gatt_if_t gatts if, 
uint16 t conn_id, 
uint32 t trans_id, 
esp gatt_status_t status, 
esp gatt_rsp t *rsp) 








Includes: 


¢ #include <esp_gatts_api.h> 
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esp_ble_gatts_set_attr_value 
sp err t esp ble gatts set attr value ( 
uintl6 t attr_handle, 
uintl6 t length, 
const uint8 t *value) 








Includes: 


¢ #include <esp_gatts_api.h> 


esp_ble_gatts_start_service 
sp_err t esp ble gatts_start_service(uintl6 t service handle) 








Includes: 


¢ #include <esp_gatts_api.h> 


esp_ble_gatts_stop_service 
sp err t esp _ ble gatts_stop service(uintl6 t service handle) 








Includes: 


¢ #include <esp_gatts_api.h> 


esp_ble_resolve_adv_data 
Resolve Advertized data. 





uint8 t *esp ble resolve adv_data( 

uint8 t *adv_data, 

uint8 t type, 

uint8 t *length) 
When a GAP protocol callback occurs, one of the event types that can cause this is the 
ESP _GAP BLE SCAN RESULT _EVT which indicates that we have received a scan result. If 
found, we can further ask what kind of a result and we can get an 
ESP GAP SEARCH INQ RES EVT. If that is the case, then our ADV data is good and we 


can "decode it". 









































The adv_data is a pointer to the advertized data. 


The type specifies the decode value. In the spec this is also known as the "Advertising 
Data Type" 





* ESP BLE AD TYPE FLAG (0x01) — The advert contains flags that are defined as 
following: 


o Bit O —LE Limited Discoverable Mode 
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o Bit 1-— LE General Discoverable Mode 

o Bit 2—BR/EDR is NOT supported. 

o Bit 3 — Indicates whether LE and BR/EDR Controller operates simultaneously 
o Bit 4 — Indicates whether LE and BR/EDR Host operates simultaneously 

°o Bits 5-7 — Reserved. 





ESP BLE AD TYPE 16SRV_PART (0x02) — Incomplete list of 16bit service class 
UUIDs. 


ESP_BLE_AD_TYPE_16SRV_CMPL (0x03) 
ESP_BLE_AD_TYPE_32SRV_PART (0x04) 
ESP_BLE_AD TYPE _32SRV_CMPL (0x05 























ESP BLE AD TYPE 128SRV_PART (0x06) — Incomplete list of 16bit service class 
UUIDs. 


ESP_BLE_AD_TYPE_128SRV_CMPL (x07) 


























ESP BLE AD TYPE NAME SHORT (0x08) — Shortened local name. 



































ESP BLE AD TYPE NAME CMPL (0x09) — Complete local name. 
ESP_BLE_AD_TYPE_TX_PWR (0x0A) 
ESP_BLE_AD_TYPE_DEV_CLASS (0x0D) 
ESP_BLE_AD_TYPE_SM_TK (0x10) 
ESP_BLE_AD_TYPE_SM_OOB_ FLAG (0x11) 
ESP_BLE_AD_TYPE_INT_RANGE (0x12) 
ESP_BLE_AD_TYPE_SOL_SRV_UUID (0x14) 
ESP_BLE_AD_TYPE_128SOL_SRV_UUID (0x15) 
ESP_BLE_AD_TYPE_SERVICE_DATA (0x16) 
ESP_BLE_AD_TYPE_PUBLIC_TARGET (0x17) 
ESP_BLE_AD_TYPE_RANDOM_TARGET (0x18) 


ESP_BLE_AD_TYPE_APPEARANCE (0x19) — It is likely this conforms to the 
assigned numbers found here 
https://www.bluetooth.com/specifications/gatt/viewer? 
attributeXmIFile=org.bluetooth.characteristic.gap.appearance.xml and 


ESP_BLE_AD_TYPE_ADV_INT (0x1A) 
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- ESP_BLE_AD TYPE_32SOL_SRV_UUID (0x1B) 
- ESP_BLE_AD_ TYPE_32SERVICE_DATA (0x1C) 
- ESP_BLE_AD TYPE_128SERVICE_DATA (0x1D) 








* ESP BLE AD MANUFACTURER SPECIFIC TYPE (0xFF) — Custom payload. 























The length is the length of the advertized data. 
Includes: 

¢ #include <esp_gap_ble_api.h> 
See also: 


GAP Advertizing data 
esp_ble_gap_register_callback 


esp_bluedroid_deinit 
Disable and release all resources for bluetooth. 





sp_err_ t esp _bluedroid_ deinit (void); 
Includes: 


¢ #include <esp_bt_main.h> 


esp_bluedroid_disable 
Disable bluetooth. 


sp_err t esp bluedroid disable (void) 





Includes: 


¢ #include <esp_bt_main.h> 


esp_bluedroid_enable 
Enable bluetooth. 


sp_err t esp bluedroid enable (void) 





Includes: 


¢ #include <esp_bt_main.h> 


esp_bluedroid_init 
Initialize and enable bluetooth resources. 
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sp_err t esp bluedroid init (void) 
Includes: 


¢ #include <esp_bt_main.h> 


esp_bt_controller_init 
esp err t esp bt controller init(esp bt_controller config t *cfg) 





Typically, we will code this as: 








esp bt _controller config t bt_cfg = BT CONTROLLER INIT CONFIG DEFAULT () ; 


ret = esp bt controller init (&bt_cfg); 
Includes: 


¢ #include <bt.h> 


esp_bt_controller_enable 
Enable the bluetooth controller. 


esp_err t esp _bt_ controller enable(esp bt _mode_t mode) 





The value of mode can be one of: 





* ESP BT MODE ILDE— Not run. 














* ESP BT MODE BLE - BLE mode. 




















* ESP_BT MODE CLASSIC_BT — Classic mode. 


























* ESP _BT MODE BTDM— Dual mode. 








Note: Currently only esp BT MODE BTbM is supported. 
Includes: 


¢ #include <bt.h> 


esp_vhci_host_check_send_available 
bool esp vhci host check send available () 





Includes: 


¢ #include <bt.h> 
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esp_vhci_host_register_callback 
void esp _vhci_ host register callback(const esp vhci_host_callback_t *callback) 


Includes: 


¢ #include <bt.h> 


esp_vhci_host_send_packet 
void esp vhci_host_ send packet (uint8 t *data, uintl6 t len) 





Includes: 
¢ #include <bt.h> 


Upgrade APIs 


system_upgrade_flag_check 
Retrieve the upgrade status flag. 


uint8 system_upgrade flag check () 
The returned value will be one of: 


° UPGRADE FLAG IDLE — 











* UPGRADE FLAG START — 








* UPGRADE FLAG FINISH — 





system_upgrade_flag_set 
Set the upgrade status flag. 


void system_upgrade flag _set(uint8 flag) 
The flag can be one of: 


° UPGRADE FLAG IDLE — 











* UPGRADE FLAG START — 








° UPGRADE FLAG FINISH — 





system_upgrade_reboot 
Reboot the ESP8266 and run the new firmware. 


void system_upgrade_ reboot () 
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system_upgrade_start 
Start downloading the new firmware from the server. 


bool system_upgrade start(struct upgrade server info *server) 


The server parameter is a structure ... 


system_upgrade_userbin_check 


Determine which of the two possible firmware images can be upgraded. 


uint8 system_upgrade_userbin_ check () 








The result will be either UPGRADE FW _BIN1 Of UPGRADE FW BIN2. 


Smart config APIs 


smartconfig_start 
bool smartconfig_start(sc_callback_t cb, uint8 log) 


smartconfig_stop 
bool smartconfig_ stop (void) 


SNTP API 
Handle Simple Network Time Protocol requests. 


See also: 


Working with SNTP 


sntp_enabled 
Determine whether or not SNTP is enabled. 


ug _t sntp_enabled() 
Includes: 


¢ #include <apps/sntp/sntp.h> 


sntp_getoperatingmode 
Retrieve the current operating mode. 


us t sntp_getoperatingmode () 


The operating mode returned can be one if: 
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* SNTP_OPMODE POLL — This is the default. 

















* SNTP_ OPMODE LISTENONLY _- 
Includes: 


¢ #include <apps/sntp/sntp.h> 


sntp_getserver 
ip _addr_t sntp_getserver(u8 t idx) 


Includes: 


¢ #include <apps/sntp/sntp.h> 


sntp_getservername 
Get the hostname of a target SNTP server. 


char *sntp_setservername (u8 t index) 
Retrieve the host name of a specific SNTP server that was previously registered. 


The index parameter is the index of an SNTP server that was previously set. It may be 
either 0, 1 or 2. 


The return from this function is a NULL terminated string. 
Includes: 
¢ #include <apps/sntp/sntp.h> 


See also: 


Working with SNTP 


sntp_init 
void sntp_init() 


Initialize the SNTP functions. Prior to calling this function, set the operating mode and 
server name. 


Includes: 
¢ #include <apps/sntp/sntp.h> 


See also: 


Working with SNTP 
sntp_stop 
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sntp_servermode_dhcp 
Enable use of DHCP for SNTP server location. 


sntp_servermode_ dhcp(int setServersFromDhcp) 


The setServersFromDhcp Is a flag that should be 1 or 0. If set to 1, then we are 
requesting that the servers to be used for SNTP should be requested from the DHCP 
server. 


Includes: 


¢ #include <apps/sntp/sntp.h> 


sntp_setoperatingmode 
Set the operating mode of SNTP access. 


void sntp_setoperatingmode (u8_t operatingMode) 
Operating mode can be one of: 


* SNTP_OPMODE POLL — This is the default. 











° SNTP_ OPMODE LISTENONLY — 








Includes: 


¢ #include <apps/sntp/sntp.h> 


sntp_setserver 
Set the address of an SNTP server. 


void sntp_serverserver(u8 t index, ip addr _t *addr) 
Set the address of one of the three possible SNTP servers to be used. 


The index parameter must be either 0, 1 or 2 and specifies which of the SNTP server 
slots is to be set. 


The addr parameter is the IP address of the SNTP server to be recorded. 
Includes: 
¢ #include <apps/sntp/sntp.h> 


See also: 


Working with SNTP 
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sntp_setservername 
Set the host name of a target SNTP server. 


void sntp_setservername(u8_ t index, char *server) 
Specify an SNTP server by its host name. 


The index parameter is the index of an SNTP server to be set. It may be either 0, 1 or 
2. 


The server parameter is a NULL terminated string that names the host that is an SNTP 
server instance. 


Includes: 
¢ #include <apps/sntp/sntp.h> 


See also: 


Working with SNTP 


sntp_stop 
Stop SNTP processing. 


void sntp_stop() 
Includes: 
¢ #include <apps/sntp/sntp.h> 


See also: 


Working with SNTP 


Generic TCP/UDP APIs 


ipaddr_addr 
Build a TCP/IP address from a dotted decimal string representation. 


uint32 ipaddr_addr(char *addressString) 
Return an IP address (4 byte) value from a dotted decimal string representation 
supplied in the addressString parameter. Note that the uint32 type is not assignable to 


the addresses in an esp_tcp or esp_udp structure. Instead we have to use a local 
variable and then copy the content. For example: 


uint32 addr = ipaddr_ addr (server) ; 
memcpy (m_tcp.remote ip, é&addr, 4); 


IP4_ADDR 
Set the value of a variable to an IP address from its decimal representation. 
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IP4 ADDR(struct ip addr * addr, a, b, c, d) 


The addr parameter is a pointer to storage to hold an IP address. This may be an 
instance of struct ip addr, a uint32, uint8[4]. It must be cast to a pointer to a struct 
ip_addr If not already of that type. 


The parameters a, b, c and a are the parts of an IP address if it were written in dotted 
decimal notation. 


Includes: 
¢ ip_addr.h 


See also: 


. Error: Reference source not found 


IP2STR 
Generate four int values used in a printf statement 


IP2STR(ip_addr_t *address) 


This is a macro which takes a pointer to an IP address and returns four comma 
separated decimal values representing the 4 bytes of an IP address. This is commonly 
used in code such as: 


printf ("Sd.%d.%d.sd", IP2STR(é&addr) ); 


The macro rpstr can be used in place of 4 "%d" macros: 


printf(IPSTR, IP2STR(&addr) ); 
Includes: 

¢ tcpip_adapter.h 
See also: 


tcpip_adapter_get_ip_info 


MAC2STR 
Generate 6 values for a print £ format. 


MAC2STR(char *[6]) 

Use this in conjunction with the macstr macro. Here is an example: 
char mac[6]; 

auinte (MACSTR, MAC2STR(mac) ); 


Includes: 
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* rom/ets_sys.h 


TCP Adapter APIs 
The TCP/IP adapter. 


tcpip_adapter_ap_input 
Receive low level data. 


esp_err t tcpip adapter ap input ( 

void *buffer, 

uintl6 t len, 

void *eb) 
This function is exposed but somewhat of a mystery. It appears to be related to getting 
data from the WiFi layer to be supplied to the TCP/IP layer but we have no knowledge 
about when or how it might be used. 


Includes: 


¢ tcpip_adapter.h 


tcpip_adapter_create_ip6_linklocal 

esp err t tcpip adapter create ip6é linklocal(tcpip adapter if t tcpip if) 
tcpip_adapter_dhcpc_get_status 

Get the status of the DHCP client subsystem. 


esp err t tcpip adapter dhcpc_ get status ( 
tcpip adapter if t tcpip if, 
tcpip adapter dhcp status_t *status) 


The tcpip if is the interface is one of the following: 


* TCPIP ADAPTER IF Sta — Station interface. 











* TCPIP ADAPTER IF Ap —Access point interface. 
The status can be one of: 


* TCPIP ADAPTER DHCP STARTED — DHCP client has started for this interface. 

















* TCPIP ADAPTER DHCP_STOPPED — DHCP client has stopped for this interface. 


Includes: 


¢ tcpip_adapter.h 


Page 556 


tcpip_adapter_dhcpc_option 
esp_err t tcpip adapter dhcpc_ option ( 
tcpip adapter option _mode_t opt_op, 





tcpip adapter option_id_t opt_id, 
void *opt_val, uint32_t opt_len) 





The tcpip if is the interface is one of the following: 


* TCPIP ADAPTER IF Sta — Station interface. 











* TCPIP ADAPTER IF Ap —Access point interface. 
The opt_op can be one of: 


* TCPIP ADAPTER OP SET — Set the option. 

















* TCPIP ADAPTER _OP GET — Get the option. 
The opt_id can be one of: 
* TCPIP_ADAPTER_ROUTER_SOLICITATION ADDRESS 
* TCPIP_ADAPTER_REQUESTED_IP_ADDRESS 
* TCPIP_ADAPTER_IP_ADDRESS_LEASE_TIME 
* TCPIP_ADAPTER_IP_REQUEST_RETRY_TIME 


Includes: 


¢ tcpip adapter.h 


tcpip_adapter_dhcpc_start 
Start the DHCP client on the specified interface. 


esp err t tcpip adapter dhcpc_ start(tcpip adapter if t tcpip if) 
The tcpip if is the interface is one of the following: 


* TCPIP ADAPTER IF Sta — Station interface. 











* TCPIP ADAPTER IF Ap —Access point interface. 


tcpip_adapter_dhcpc_stop 
Stop the DHCP client on the specified interface. 


esp err t tcpip adapter dhcpc_stop(tcpip adapter if t tcpip if) 
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The tcpip_ if is the interface is one of the following: 


* TCPIP ADAPTER IF Sta — Station interface. 











* TCPIP ADAPTER _IF ap —Access point interface. 
Includes: 


¢ tcpip_adapter.h 


tcpip_adapter_dhcps_get_status 
Retrieve the status of the DHCP server subsystem. 


esp err t tcpip adapter dhcps get status ( 
tcpip adapter if t tcpip if, 
tcpip adapter dhcp status_t *status) 


The tcpip_ if is the interface is one of the following: 


* TCPIP ADAPTER_IF_ sta — Station interface. 











* TCPIP ADAPTER IF Ap —Access point interface. 
The status parameter returns the possible states of the DHCP subsystem which are: 
* TCPIP ADAPTER DHCP_INIT -— Initial state. 


* TCPIP ADAPTER DHCP STARTED — The DHCP service is running. 

















* TCPIP ADAPTER DHCP STOPPED — The DHCP service is stopped. 


Includes: 


¢ tcpip_adapter.h 


tcpip_adapter_dhcps_option 
Set or get the options for the DHCP server 


esp err t tcpip adapter dhcps_ option ( 

tcpip adapter option mode _t optMode, 

tcpip adapter option_id_t optId, 

void *opt_val, uint32_t opt_len) 
The optMode defines whether we are getting or setting an option. The possible values 
are: 


* TCPIP ADAPTER OP SET -— Used to set an option. 

















* TCPIP ADAPTER OP GET — Used to get an option. 
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The optid defines the option being set or retrieved. The currently defined values are: 


° TCPIP_ ADAPTER ROUTER SOLICITATION ADDRESS — 








° TCPIP_ ADAPTER REQUESTED IP ADDRESS — 

















° TCPIP_ ADAPTER IP ADDRESS LEASE TIME — 












































° TCPIP ADAPTER IP REQUEST RETRY TIME — 





Includes: 


* tcpip_adapter.h 


tcpip_adapter_dhcps_start 
Start the DHCP server on the specified interface. 


esp err t tcpip adapter dhcps start(tcpip adapter if t tcpip if) 
The tcpip_if is the interface is one of the following: 


* TCPIP ADAPTER IF Sta — Station interface. 











* TCPIP ADAPTER _IF ap —Access point interface. 


Includes: 


¢ tcpip_adapter.h 


tcpip_adapter_dhcps_stop 
Stop the DHCP server on the specified interface. 
esp err t tcpip adapter dhcps_ stop(tcpip adapter if t tcpip if) 


The tcpip if is the interface is one of the following: 


* TCPIP ADAPTER IF sta — Station interface. 











* TCPIP ADAPTER IF Ap —Access point interface. 


Includes: 


¢ tcpip_adapter.h 


Page 559 


tcpip_adapter_down 
Stop the TCP/IP interface. 


esp_err t tcpip adapter down(tcpip adapter if t tcpip if) 
The tcpip_ if is the interface is one of the following: 


* TCPIP ADAPTER _IF sta — Station interface. 











* TCPIP ADAPTER _IF ap —Access point interface. 


tcpip_adapter_eth_input 
esp err t tcpip adapter eth _input(void *buffer, uintl6é t len, void *eb) 


tcpip_adapter_free_sta_list 
Release storage for the connected station list. 


esp err t tcpip adapter free sta_list(tcpip adapter sta_list_t *sta_list) 





The storage was allocated with a call to tcpip adapter get sta list(). 


Includes: 
¢ tcpip_adapter.h 
See also: 


tcpip_adapter_get_sta_list 


tcpip_adapter_get_esp_if 


esp interface t tcpip_adapter get_esp if (void *dev) 


tcpip_adapter_get_hostname 
Get the name of the interface. 


esp err t tcpip adapter get_hostname(tcpip adapter if, const char **hostname) 
The tcpip_ if is the interface is one of the following: 


* TCPIP ADAPTER _IF sta — Station interface. 











* TCPIP ADAPTER _IF ap —Access point interface. 
Includes: 

¢ tcpip_adapter.h 
See also: 


tcpip_adapter_set_hostname 
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tcpip_adapter_get_ip_info 
Get the current IP address information. 


esp err t tcpip adapter get_ip info ( 
tcpip adapter if t tcpip if, 
tcpip adapter ip info t *ipInfo) 


The tcpip_ if is the interface is one of the following: 


* TCPIP ADAPTER _IF sta — Station interface. 











* TCPIP ADAPTER IF Ap —Access point interface. 
The ipiInfo contains: 

* ip—The ip address of the interface. 

* netmask — The network mask of the interface. 


* gw-— The default gateway of the interface. 


Includes: 
¢ tcpip_adapter.h 


See also: 


IP2STR 


tcpip_adapter_get_ip6_linklocal 

esp_err t tcpip adapter get_ip6 linklocal(tcpip adapter if t tcpip_ if, ip6 addr t 
*if ip6); 

tcpip_adapter_get_sta_list 

Populate a list of tcpip adapter sta list _t from data. 

esp err t tcpip adapter get_sta_list( 


wifi _sta_list_t *sta_info, 
tcpip adapter _sta_list_t **sta_list) 





Populate a list of "tcpip adapter sta list _t" froma list of "wifi sta list _t". The 
tcpip adapter sta list _t contains: 





STAILQ ENTRY (station list) next 
uints8 t [6] mac 


ip4 addr _t ip 


Here is an example of use: 
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wifi _sta_list_t *stations; 
ESP ERROR CHECK (esp wifi get station list (&stations) ); 
tcpip adapter _sta_list_t *infoList; 














ESP_ERROR CHECK (tcpip adapter get _sta_list(stations, &infoList)); 
struct station list *head = infoList; 
while(infoList != NULL) { 

printf ("mac: %3.2x:%.2x:%3.2x:%.2x: 





S.2xeS.2x% "  TRSTR " d\n"; 
infoList->mac[0],infoList->mac[1 
infoList->mac[3],infoList->mac[4 
IP2STR(&(infoList->ip)), 
(uint32_ t) (infoList->ip.addr) ); 
infoList = STAILQ NEXT(infoList, next); 


,infoList->mac[2], 








] 
] 


,infoList->mac[5], 





} 
ESP_ERROR_ CHECK (esp adapter free sta_list (head) ); 
ESP ERROR CHECK (esp wifi free station _list()); 

















Includes: 
¢ tcpip_adapter.h 


See also: 


. esp_wifi_get_station_list 


tcpip_adapter_get_wifi_if 


wifi interface _t tcpip_adapter get _wifi_if(void *dev) 
Includes: 


¢ tcpip_adapter.h 


tcpip_adapter_init 


void tcpip adapter init (void) 
Includes: 


* tcpip_adapter.h 


tcpip_adapter_set_hostname 
Set the host name associated with the supplied interface. 


esp_err t tcpip adapter set_hostname ( 
tcpip adapter if t tcpip if, 
char *hostname) 


The tcpip_if is the interface is one of the following: 





* TCPIP ADAPTER _IF sta — Station interface. 
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* TCPIP ADAPTER IF Ap —Access point interface. 


The hostname is the host name to be associated with the interface. The maximum size 
of the host name is TcPIP HOSTNAME MAX SIZE. 








Includes: 
¢ tcpip_adapter.h 


See also: 


tcpip_adapter_get_hostname 


tcpip_adapter_set_ip_info 
Set our IP info. 
esp_err t tcpip adapter set_ip info ( 


tcpip adapter if t tcpip if, 
tcpip adapter ip info _t *ip info) 





Set the IP address of the adapter. If we are setting the station address, then the DHCP 
client must be already stopped. If we are setting the access point interface address, 
then the DHCP server must be already stopped. 


The tcpip_ if is the interface is one of the following: 


* TCPIP ADAPTER IF sta — Station interface. 











* TCPIP ADAPTER IF Ap —Access point interface. 


The ipiInfo contains: 


e ip 
* netmask 
e gw 


Each of these fields are an "ip4 addr_t" which is itself a struct containing a field called 
"addr" which is a 32bit unsigned integer. One can set the value of such an address 
using the macro "IPp4 ADDR(ip4 addr t *, int, int, int, int)". 





For example: 


tcpip_ adapter ip info _t ipInfo; 
IP4 ADDR(&ipInfo.ip, 192,168,1,99); 


Includes: 
¢ tcpip_adapter.h 


See also: 
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The DHCP client 


tcpip_adapter_sta_input 

esp err t tcpip adapter sta_input ( 
void *buffer, 
uint1l6 t len, void *eb) 


Includes: 


¢ tcpip_adapter.h 


tcpip_adapter_start 
Start the TCP/IP interface. 


esp err t tcpip adapter start ( 
tcpip adapter if t tcpip if, 
uint8 t *mac, 
tcpip adapter ip info _t *ip info) 





The tcpip_if is the interface is one of the following: 


* TCPIP ADAPTER _IF sta — Station interface. 











* TCPIP ADAPTER _IF ap —Access point interface. 
The mac contains the hardware mac address we are to use. 


The ipiInfo contains: 


- ip 
* netmask 
° gw 

Includes: 


¢ tcpip_adapter.h 


tcpip_adapter_stop 
esp_err t tcpip adapter stop(tcpip adapter if t tcpip if) 


The tcpip_ if is the interface is one of the following: 


* TCPIP ADAPTER_IF sta — Station interface. 











* TCPIP ADAPTER _IF ap —Access point interface. 
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Includes: 


¢ tcpip adapter.h 


tcpip_adapter_up 
Bring up the TCP/IP interface. 


esp_err t tcpip adapter up(tcpip adapter if t tcpip_if) 
The tcpip if is the interface is one of the following: 


* TCPIP ADAPTER _IF sta — Station interface. 











* TCPIP ADAPTER _IF ap —Access point interface. 


Includes: 


¢ tcpip_adapter.h 


mdns 
See also: 


Multicast Domain Name Systems 


mdns_free 
Stop and release resources for a previously initialized mDNS server. 


void mdns_free(mdns_ server t *server) 





The server parameter would have been previously created with a call to mdns_init(). 
Includes: 


¢ #include <mdns.h> 


mdns_init 
Initialize mDNS on an interface. 


esp_err t mdns_init( 
tcpip adapter if t tcpip if, 
mdns_ server t **server) 
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The tcpip_ if is the interface on which mDNS is being initialized. The choices are 
TCPIP ADAPTER IF STA Of TCPIP ADAPTER IF Ap. The server is a pointer that is updated 
to point to an mdns_server t data structure. That structure appears to be opaque. 








Includes: 
¢ #include <mdns.h> 


¢ #include <tcpip_adapter.h> 


mdns_query 
Search for mDNS records of a given service or protocol. 


size t mdns_query ( 





mdns_ server t *server, 
const char *service, 
const char *proto, 
uint32_t timeout) 


If the timeout is 0, then mdns_ query end() must be called to explicitly end the search. 
The return is the number of results found. 
Includes: 


¢ #include <mdns.h> 


mdns_query_end 
Terminate a query where no timeout was specified. 


size_t mdns_query end(mdns_server t *server) 








Includes: 


¢ #include <mdns.h> 


mdns_result_free 


esp err t mdns_ result _free(mdns_ server t *server) 








Includes: 


¢ #include <mdns.h> 


mdns_result_get 
Get a specific result by index. 
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const mdns_result_t * mdns_result_get ( 
mdns_ server t *server, 





size_t num) 
Includes: 


¢ #include <mdns.h> 


mdns_result_get_count 
Get the number of results currently in memory. 


size t mdns_result_get_count(mdns_ server t * server) 





Includes: 


¢ #include <mdns.h> 


mdns_service_add 
Define a service we are advertizing when we are being an mDNS responder/server. 


esp err t mdns_service add ( 
mdns_ server t *server, 





const char *service, 
const char *proto, 
uint16 t port) 


The server is the value we got when we previously called mdns_init () to initialize 
ourselves as an mDNS responder. 


The port is the port number on which our advertized service will be listening on for 
incoming connections. 


We can Call mdns service remove() to remove a service. 





Includes: 


¢ #include <mdns.h> 


mdns_service_instance_set 


esp err t mdns_ service instance set ( 





mdns_ server t *server, 
const char *service, 
const char *proto, 
const char *instance) 


Includes: 


¢ #include <mdns.h> 


Page 567 


mdns_service_port_set 
esp err t mdns_ service port_set( 





mdns_ server t *server, 
const char *service, 
const char *proto, uint1l6 t port) 


Includes: 


¢ #include <mdns.h> 


mdns_service_remove 


esp_err_t mdns_service_remove ( 





mdns_ server t *server, 
const char *service, 
const char *proto) 


We call mdns_ service _add() to add a service. 
Includes: 


¢ #include <mdns.h> 


mdns_service_remove_all 


esp_err t mdns_service remove _all(mdns_server t *server) 





Includes: 


¢ #include <mdns.h> 


mdns_service_txt_set 
esp err t mdns_ service txt_set( 





mdns_ server t *server, 
const char *service, 
const char *proto, 
uint8 t num_items, 
const char **txt) 


The txt is an array of strings where each entry is of the form "name=value". 
Includes: 


¢ #include <mdns.h> 


mdns_set_hostname 
Set the host name of our mDNS server. 
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esp err t mdns set hostname ( 








mdns_ server t *server, 
const char *hostname) 


Includes: 


¢ #include <mdns.h> 


mdns_set_instance 
Set the instance name for our MDNS server. 


esp err t mdns set instance ( 





mdns_ server t *server, 





const char *instance) 
Includes: 


¢ #include <mdns.h> 


OTA 
Over The Air (OTA) is the capability to save a new image in flash for subsequent 
execution on next boot/restart. 


Here is how we believe OTA works: 

1. We call esp_ota_begin() to start the beginning of an OTA image write 

2. We receive data that is part of the image 

3. We call esp_ota_write() to write the data we just read 

4. Go back to 2 while there is more of the image to receive over the network 
5. We call esp_ota_end() to flag the end of the OTA image write 


6. We call esp_ota_set_boot_partition() to specify which partition will be booted on next 
reboot 


esp_ota_begin 
esp err t esp ota begin ( 





const esp partition _t* partition, 
size t image size, 
esp ota handle t* out handle) 





Includes: 


esp_ota_ops.h 


Page 569 


esp_ota_end 
Finish the update and validate the image. 


esp err t esp ota_end(esp ota_handle t handle) 





The handle comes from a previous Call to esp_ota_begin(). 


Includes: 


esp_ota_ops.h 


esp_ota_get_boot_partition 
Get the partition information of the current boot partition. 


const esp partition_t *esp ota_get_boot_ partition (void) 





Includes: 


esp_ota_ops.h 


esp_ota_set_boot_partition 
Set the partition of the next partition to be booted. 


esp err t esp ota_set_boot_partition(const esp partition_t *partition) 





Includes: 


esp_ota_ops.h 


esp_ota_write 
esp err t esp ota write ( 





esp _ota_handle t handle, 
const void *data, size t size) 


The handle comes from a previous Call to esp ota begin(). 


Includes: 


esp_ota_ops.h 


GPIO Driver 

The gpio functions in the ESP32 are provided through the ESP-IDF. One must include 
the "driver/gpio.h" header. 

See also: 


GPIOs 
Analog to Digital Conversion 
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gpio_config 
Configure one or more GPIO settings in a single operation. 
esp_err t gpio_config(gpio_config_t *pGPIOConfig) 
The gpio config t data structure contains: 

uinto4 t pin bit _mask 

gpio_mode_t mode 
gpio pullup t pull _up en 

gpio_ pulldown _t pull down _en 





gpio_ int type t intr type 





The pin bit mask defines which pins we are configuring. Constants are defined to 
assist us here. For example, if we are configuring GPIO16 and GPIO34 we can set the 
pin bit mask tO GPIO SEL 16 | GPIO_SEL 34 which is the boolean "or" of the two 
constant values. 








The mode Is used to set the mode of all of the pins we are configuring. The allowable 
values are: 


° GPIO MODE INPUT 


° GPIO MODE OUTPUT 








° GPIO MODE OUTPUT OD 


° GPIO MODE INPUT OUTPUT OD 






































°  GPIO MODE INPUT OUTPUT 





The pull_up en enables an internal pull-up resistor. The allowable values are: 





* GPIO_PULLUP_ENABLE 


























° GPIO PULLUP DISABLE 


The pull _down_en enables an internal pull-down resistor. The allowable values are: 





° GPIO PULLDOWN ENABLE 

















° GPIO_ PULLDOWN DISABLE 











The intr type configures how interrupts are handled for the pin. The allowable values 
are: 


° GPIO_INTR_ DISABLE 





° GPIO_INTR_POSEDGE 




















° GPIO_INTR_NEGEDGE 
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° GPIO_INTR_ANYEDGE 




















* GPIO INTR LOW LEVEL 














* GPIO INTR HIGH LEVEL 








Here is an example: 


gpio_config t gpioConfig; 
gpioConfig.pin_ bit mask = (1 << 16) | (1 << 17); 
gpioConfig.mode = GPIO MODE OUTPUT; 
gpioConfig.pull_up_en = GPIO PULLUP_DISABLE; 
gpioConfig.pull down _en = GPIO PULLDOWN_ DISABLE 
gpioConfig.intr type = GPIO INTR_DISABLE 
gpio_config(&gpioConfig) ; 

















~ 


Includes: 


¢ #include <driver/gpio.h> 


gpio_get_level 
Retrieve the signal level on the pin. 


int gpio_get_level(gpio num_t gpioNum) 


Get the signal level on the specified pin. EitherO or 1. The direction of the pin should 
be set to be INPUT to retrieve a useful result. 


Includes 
¢ #include <driver/gpio.h> 


See also: 


gpio_set_direction 
GPIOs 


gpio_install_isr_service 
Install a GPIO ISR service. 


esp_err t gpio_install_isr_ service(int intr alloc flags) 
Includes: 
¢ #include <driver/gpio.h> 


See also: 


gpio_uninstall_isr_service 
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gpio_intr_enable 
Enable interrupts on the specified pin. 


esp_err t gpio_intr_enable(gpio num_t gpioNum) 





Enabling the interrupt on the pin will cause an interrupt trigger when the type of interrupt 
as specified by gpio set intr type() occurs. 


Includes 
¢ #include <driver/gpio.h> 


See also: 


GPIO Interrupt handling 
gpio_set_intr_type 
gpio_intr_disable 


gpio_intr_disable 
Disable interrupts on the specified pin. 


esp_err t gpio_intr disable(gpio_num_t gpioNum) 





Disabling the interrupt on the pin will prevent an interrupt trigger from being registered. 
Includes 
¢ #include <driver/gpio.h> 


See also: 


gpio_intr_enable 


gpio_isr_handler_add 
Associate an ISR with a given pin. 
esp_err t gpio_isr handler add( 


gpio_num_t gpio num, 
gpio_isr_t isr_ handler, 





void* args) 


The gpio_num is the pin to which we are associating an interrupt handler. This can be 
one of the cPto_NuM xx values. 
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The isr handler Is the function we wish to invoke to process the interrupt. The handler 
does not need to be declared in instruction RAM unless the ISR is defined with the 
ESP _INTR_ FLAG TRAM. 





The signature of an interrupt handler function is: 


void func(void *args) 
The args is a pointer that will be passed to the ISR. 
Includes: 

¢ #include <driver/gpio.h> 


See also: 


gpio_isr_handler_remove 
GPIO Interrupt handling 


gpio_isr_handler_remove 
Remove a previously associated ISR handler. 


esp_err t gpio_isr handler remove(gpio num_t gpio_num) 





The gpio_num identifies the pin against which any ISR handler should be removed. This 
can be one of the cpio _NumM_xx values. 


Includes: 
¢ #include <driver/gpio.h> 


See also: 


gpio_isr_handler_add 


gpio_isr_register 
Register an interrupt handler. 


esp err t gpio isr register ( 
uint32 t gpiolntr, 





void (*fn) (void *), void *arg, 

int intr_alloc_ flags, 

gpios_isr handle t handle) 
The fn is a function that will be called to handle the interrupt. The implementation of 
this function must reside in instruction RAM (IRAM) as it must be handled as quickly as 
possible and we can't afford loading it from flash. The function must be defined with the 
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"TRAM ATTR" function to force it to be in IRAM. The arg is a parameter passed into the 
interrupt handler function (£n). 


The handle is a handle used to reference this ISR and is populated on return from this 
call. 


Includes 
¢ #include <driver/gpio.h> 


See also: 


GPIO Interrupt handling 


gpio_set_direction 
Set the direction of a pin. 


esp err t gpio_set_direction(gpio num_t gpioNum, gpio_mode _t mode) 





The mode is used to set the mode of the pin we are configuring. The allowable values 
are: 


° GPIO MODE INPUT 


° GPIO MODE OUTPUT 








° GPIO MODE OUTPUT OD 


° GPIO MODE INPUT OUTPUT OD 






































°  GPIO MODE INPUT OUTPUT 





Includes: 
¢ #include <driver/gpio.h> 


See also: 


GPIOs 
gpio_get_level 
gpio_set_level 


gpio_set_intr_type 
Set the interrupt type of a pin. 


esp err t gpio_set_intr_type(gpio_num_t gpioNum, gpio_int_ type _t intrType) 
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The gpioNum defines which pins is having its interrupt type changed. This can be one of 
the GPIo_ NUM xx values. 


The intr type configures how interrupts are handled for the pin. The allowable values 
are: 





° GPIO_INTR_ANYEDGE 








° GPIO_INTR_ DISABLE 





° GPIO_INTR_ NEGEDGE 




















° GPIO_INTR_POSEDGE 





° GPIO_INTR LOW LEVEL 






































* GPIO INTR_HIGH_ LEVEL 
Includes 
¢ #include <driver/gpio.h> 


See also: 


gpio_isr_register 


gpio_set_level 
Set the level of a pin. 


esp err t gpio_set_level(gpio num_t gpioNum, uint32_ t level) 





Se the level of an output pin. The 1evel1 should be either 0 or 1. 
Includes: 
¢ #include <driver/gpio.h> 


See also: 


GPIOs 
gpio_set_direction 
gpio_get_level 


gpio_set_pull_mode 
Set the pullup/pulldown mode of the pin. 


esp_err t gpio_set_pull mode(gpio_ num_t gpioNum, gpio_ pull mode _t pull) 





The allowable values for pull are: 
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* GPIO PULLUP ONLY — Set the pin to be pulled-up. If no active signal on the pin, it will 
register as high. 
* GPIO PULLDOWN ONLY — Set the pin to be pulled-down. If no active signal on the pin, it 
will register as low. 
* GPIO PULLUP PULLDOWN — Set the pin to be both pulled-up and pulled-down so that if 
there is no actual signal on the input, it will be ”% the reference voltage. 

* GPIO FLOATING —No pull-up or pull-down. It is not defined what signal will be read from 

this pin if there is no active signal. 

Includes: 























¢ #include <driver/gpio.h> 


See also: 


Pullup and pull down settings 


gpio_uninstall_isr_service 


void gpio_uninstall _isr_ service () 
Includes: 
¢ #include <driver/gpio.h> 


See also: 


gpio_install_isr_service 


gpio_wakeup_enable 
Enable GPIO wake-up. 


esp err t gpio_ wakeup _enable(gpio_num_t gpioNum, gpio_int_ type _t intrType) 





Wake-up a sleeping device when an interrupt occurs. The allowable interrupt types are: 
¢ GPIO_INTR_LOW_LEVEL 
¢ GPIO_INTR_HIGH_LEVEL 

Includes 
¢ #include <driver/gpio.h> 


See also: 


gpio_wakeup_disable 


gpio_wakeup_disable 
Disable GPIO wake-up. 


Page 577 


esp err t gpio_wakeup disable(gpio num_t gpioNum) 





Disable waking up on a pin interrupt. 
Includes 
¢ #include <driver/gpio.h> 


See also: 


gpio_wakeup_enable 


GPIO Low Level 

gpio_init 

Initialize GPIO. 

void gpio init() 

This is a ROM exposed function. It should not be called in normal applications. 
Includes 


¢ #include <rom/gpio.h> 


gpio_input_get 
Retrieve a bit-mask of the values of the first 32 GPIOs (0-31). 


uint32 t gpio input get () 





Includes: 


¢ #include <rom/gpio.h> 


gpio_input_get_high 
Retrieve a bit-mask of the values of the last 8 GPIOs (32-39). 


uint32 t gpio input get high () 





Includes: 


¢ #include <rom/gpio.h> 


gpio_intr_ack 
void gpio_intr_ack(uint32_t ackMask) 
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This is a ROM exposed function. It is not expected to be called in normal applications. 
Includes: 


* rom/gpio.h 


gpio_intr_ack_high 


void gpio_intr_ack high(uint32_t ackMask) 
This is a ROM exposed function. It is not expected to be called in normal applications. 
Includes 


¢ #include <rom/gpio.h> 


gpio_intr_handler_register 
void gpio_intr_ handler register ( 
gpio_intr handler fn _t fn, 
void *arg) 
This is a ROM exposed function. It is not expected to be called in normal applications. 
Includes 


¢ #include <rom/gpio.h> 


gpio_intr_pending 
uint32 t gpio_intr_ pending () 


This is a ROM exposed function. It is not expected to be called in normal applications. 
Includes 


¢ #include <rom/gpio.h> 


gpio_intr_pending_high 


uint32 t gpio_intr pending high () 
This is a ROM exposed function. It is not expected to be called in normal applications. 
Includes 


¢ #include <rom/gpio.h> 


Page 579 


gpio_matrx_in 

void gpio matrix in/( 
uint32_ t gpioNum, 
uint32 t signalldx, 
bool inv) 


Includes 
¢ #include <rom/gpio.h> 


See also: 


Pads and multiplexing 


gpio_matrix_out 
Set the signal output to a given gpio. 
void gpio_ matrix out ( 

uint32_t gpio, 

uint32 t signalldx, 

bool outInv, 

bool oenInv) 
The gpio is the gpio output number between 0 and 39. The signalidx is the index of 
the signal to be sent to that gpio. To invert the signal set out Inv to be 1. To invert the 
signal output enable set oenInv to be 1. 


Includes 
¢ #include <rom/gpio.h> 


See also: 


Pads and multiplexing 


gpio_output_set 
Set GPIOs that need to be input, output, high or low on bulk 
void gpio_output_set ( 

uint32 t setMask, 

uint32_ t clearMask, 

uint32_t enableMask, 

uint32_ t disableMask) 
Work with the first 32 GPIOs (0-31) specifying which ones are input, which ones are 
output, which ones should be left alone and which ones should be set high/low. This 
API lets us set a batch of GPIOs in one operation. 


Includes 
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¢ #include <rom/gpio.h> 


gpio_output_set_high 
Set GPIOs that need to be input, output, high or low on bulk 


void gpio_output_set_high ( 
uint32 t setMask, 
uint32_ t clearMask, 
uint32_t enableMask, 
uint32_ t disableMask) 


Work with the last 8 GPIOs (32-39) specifying which ones are input, which ones are 
output, which ones should be left alone and which ones should be set high/low. This 
API lets us set a batch of GPIOs in one operation. 


Includes 


¢ #include <rom/gpio.h> 


gpio_pad_hold 


void gpio_pad_hold(uint8 t gpioNum) 
Includes 


¢ #include <rom/gpio.h> 


gpio_pad_pulldown 


void gpio_pad_pulldown(uint8 t gpioNum) 
Includes 


¢ #include <rom/gpio.h> 


gpio_pad_pullup 


void gpio_pad_pullup(uint8 t gpioNum) 
Includes 


¢ #include <rom/gpio.h> 
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gpio_pad_select_gpio 
Specify that a given pin should be used for GPIO. 


void gpio_ pad_select_ gpio(uint8 t gpioNum) 
The gpioNum is the identity of the GPIO (0-39). 
Includes 


¢ #include <rom/gpio.h> 


See also: 


GPIOs 


gpio_pad_set_drv 


void gpio_ pad_set_drv(uint8 t gpioNum, uint8 t drv) 
Includes 


¢ #include <rom/gpio.h> 


gpio_pad_unhold 


void gpio_pad_unhold(uint8 t gpioNum) 
Includes 


¢ #include <rom/gpio.h> 


gpio_pin_wakeup_disable 
void gpio_ pin wakeup disable () 


This is a ROM exposed function. It is not expected to be called in normal applications. 
Includes 


¢ #include <rom/gpio.h> 
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gpio_pin_wakeup_enable 
void gpio_ pin wakeup _enable(uint32 t I, GPIO_ INT TYPE intrState) 





This is a ROM exposed function. It is not expected to be called in normal applications. 
Includes 


¢ #include <rom/gpio.h> 


Analog to Digital Conversion 
See also: 


Analog to digital conversion 


adc1_config_channel_atten 
Change the attenuation value of the channel. 


esp err t adcl_config channel atten ( 





adcl_channel_ t channel, 
adc_atten_t atten) 


By default, the input voltage can be between OV and 1V, however using the attenuation 
values, we can scale the voltage to be between 0-1.34V, 0-2V and 0-3.6V. 


The channel can be between apc1_ CHANNEL 0 and ADC1_ CHANNEL 7. 








The atten can be one of: 
¢ ADC_ATTEN_Odb — 1/1 
¢ ADC_ATTEN_2_5db — 1/1.34 
¢ ADC_ATTEN_6db — 1/2 
¢ ADC_ATTEN_11db — 1/3.6 
Includes: 


¢ #include <driver/adc.h> 


adc1_config_width 
Set the ADC resolution. 


esp_err t adcl_config width(adc_ bits width_t width bit) 





The width bit value may be one of: 


- ADC WIDTH _9Bit 


Page 583 


¢ ADC_WIDTH_10Bit 

¢ ADC_WIDTH_11Bit 

¢ ADC_WIDTH_12Bit 
Includes: 


¢ #include <driver/adc.h> 


adc1_get_voltage 
Read the digital value of the analog input. 


int adcl_get _voltage(adcl_ channel t channel) 

If the value <0 then an error was encountered otherwise the value is the digital value of 
the voltage on the channel. The channel can be between apc1_ CHANNEL 0 and 
ADC_CHANNEL 7. 








Includes: 


¢ #include <driver/adc.h> 


hall_sensor_read 
int hall _ sensor read() 


UART driver API 
The ESP-IDF provides a driver for the UART interfaces. 


See also: 


Working with UART/serial 


uart_clear_intr_status 
esp err t uart clear intr status ( 





uart_port_t uart_num, 
uint32_t clr_mask) 


The uart_no Is the identity of the UART being changed. It can be one of varT Num _0, 
UART_NUM_1 Of UART_NUM_2. 


The clr _mask represents the bits to be cleared. 
Includes: 
¢ #include <drivers/uart.h> 


See also: 
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uart_disable_intr_mask 

esp err t uart_ disable intr_mask( 
uart_port_t uart_num, 
uint32 t disable mask) 


The uart_no Is the identity of the UART being changed. It can be one of varT Num _0, 
UART_NUM_1 Of UART_NUM 2. 


The disable mask represents the bits to be disabled. 
Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_driver_delete 
Un-install the UART driver. 


esp_err t uart_driver delete(uart_port_t uart_num) 





The uart_no Is the identity of the UART being changed. It can be one of varT_num_0, 
UART_NUM_1 Of UART_NUM 2. 


Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_driver_install 


esp err t uart driver install ( 





uart_port_t uart_num, 
int rx buffer size, 
int tx buffer size, 
int queue_size, 

void *uart_queue, 

int intr_alloc_ flags) 





The uart_no Is the identity of the UART being changed. It can be one of varT_Num_0, 
UART_NUM_1 Of UART_NUM 2. 
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The rx buffer size is the size of the receiving ring buffer. This should be greater than 
the constant UART_FIFO_LEN. 


The tx buffer size is the size of the transmitting ring buffer. If 0, then UART output 
will block until the data is sent. 


The queue size is the size of the event queue. 


The uart queue, if set to NULL, means no event queue. If we wish, we can specify the 
address of an instance of a FreeRTOS QueueHandle t variable. If we specify that, then 
events related to the UART will be posted to the queue. We can then use FreeRTOS 
functions such aS xQueueReceive() to read events. An event is a uart event type t 
value that can be one of: 





* uaRT pata — Data is available. 





. UART BREAK — 


© UART BUFFER FULL — 





* UART FIFO ov —A queue overflow was detected. 





bd UART FRAME ERR — 











* UART PARITY ERR —A data parity error was detected. 











. UART DATA BREAK — 





The intr alloc flags are one or more flags or'd together. The value of 0 is a good 
default. 





Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_disable_intr_mask 
esp err t uart_disable intr _mask(uart_port_t uart_num, uint32_t disable mask) 


The uart_no Is the identity of the UART being changed. It can be one of varT Num _0, 
UART_NUM_1 Of UART_NUM_ 2. 


Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 
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uart_disable_pattern_det_intr 
esp_err t uart_disable pattern det _intr(uart_port_t uart_num) 


Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_disable_rx_intr 
esp err t uart_disable rx _intr(uart_port_t uart_num) 


The uart_no Is the identity of the UART being changed. It can be one of varT Num _0, 


UART_NUM_1 OF UART_NUM 2. 
Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_disable_tx_intr 
esp err t uart disable tx_intr(uart_port_t uart_num) 


The uart_no Is the identity of the UART being changed. It can be one of varT Num _0, 


UART_NUM_1 Of UART_NUM 2. 
Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_enable_intr_mask 
Enable interrupts for the UART. 


esp err t uart enable intr mask ( 





uart_port_t uart_num, 
uint32 t enable mask) 


The uart_no Is the identity of the UART being changed. It can be one of varT Num _0, 


UART_NUM_1 Of UART_NUM_ 2. 


The enable mask are the bit fields set for the ESP32 register called vart INT 








iNA 
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Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_enable_pattern_det_intr 
esp_err t uart_enable pattern det_intr ( 








uart_port_t uart_num, 
char pattern chr, 
uint8 t chr_num, 

int chr tout, 

int post_idle, 

int pre idle); 


Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_enable_rx_intr 
esp_err t uart_enable rx _intr(uart_port_t uart_num) 





The uart_no Is the identity of the UART being changed. It can be one of varT_Num_0, 
UART_NUM_1 Of UART_NUM 2. 


Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_enable_tx_intr 
esp err t uart enable tx intr ( 





uart_port_t uart_num, 
int enable, int thresh) 


The uart_no Is the identity of the UART being changed. It can be one of varT Num _0, 
UART_NUM_1 Of UART_NUM 2. 


Includes: 
¢ #include <drivers/uart.h> 


See also: 
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uart_flush 
esp _err t uart_flush(uart_port_t uart_num) 


The uart_no Is the identity of the UART being changed. It can be one of varT Num _0, 
UART_NUM_1 Of UART_NUM 2. 


Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_get_baudrate 
Get the current baud rate. 


esp err t uart get baudrate( 





uart_port_t uart_num, 
uint32_ t *baudrate) 


The uart_no Is the identity of the UART being changed. It can be one of varT_Num_0, 
UART_NUM_1 Of UART_NUM 2. 


The baud_rate Is the current transmission rate in bits per second. 
Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_get_buffered_data_len 
esp err t uart_get_ buffered data_len(uart_port_t uart_num, size t * size) 





Get the size of data buffered in the RX ring buffer waiting to be read. 
Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 
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uart_get_hw_flow_ctrl 
esp err t uart get hw flow ctrl( 





uart_port_t uart_num, 
uart_hw_flowcontrol t *flow_ctrl) 


The uart_no Is the identity of the UART being changed. It can be one of vart Num _0, 
UART_NUM_1 OF UART_NUM 2. 


Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_get_parity 
Get the current parity setting. 


esp err t uart get parity ( 
uart_port_t uart_num, 





uart_parity t *parity mode) 


The uart_no Is the identity of the UART being changed. It can be one of varT Num _0, 
UART_NUM_1 Of UART_NUM_2. 

















The parity mode Can be one of varT PARITY DISABLE, UART PARITY EVEN, 





UART_ PARI TY ODD. 
Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_get_stop_bits 
esp err t uart get stop bits ( 





uart_port_t uart_num, 
uart_stop bits t *stop bits) 


Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 
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uart_get_word_length 
Get the current word length of a transmission. 


esp err t uvart get word length ( 





uart_port_t uart_num, 
uart_word_ length _t *data_bit) 


The uart_no Is the identity of the UART being changed. It can be one of varT_Num_0, 


UART_NUM_1 Of UART_NUM 2. 


The data_bit is the word length being used for a transmission. It can be one of 
UART DATA 5 BITS, UART DATA 6 BITS, UART_DATA 7 BITS Of UART DATA 8 BITS. 





Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_intr_config 
esp err t uart intr config ( 





uart_port_t uart_num, 
const uart_intr config t *intr_conf) 


The uart_no Is the identity of the UART being changed. It can be one of varT Num _0, 
UART_NUM_1 Of UART_NUM_2. 


The intr_conf is a structure containing: 
¢ intr_enable_mask 

o UART_RXFIFO_FULL_INT_ENA_M 
o UART_TXFIFO_EMPTY_INT_ENA_M 
o UART_PARITY_ERR_INT_ENA_M 
o UART_FRM_ERR_INT_ENA_M 
o UART_RXFIFO_OVF_INT_ENA_M 
o UART_DSR_CHG_INT_ENA_M 
o UART_CTS_CHG_INT_ENA_M 
o UART_BRK_DET_INT_ENA_M 
o UART_RXFIFO_TOUT_INT_ENA_M 
o UART_SW_XON_INT_ENA _M 
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o UART_SW_XOFF_INT_ENA_M 
0 UART_GLITCH_DET_INT_ENA_M 
o UART_TX_BRK_DONE_INT_ENA M 
o UART_TX_BRK_IDLE_DONE_INT_ENA M 
o UART_TX_DONE_INT_ENA_M 
o UART_RS485_PARITY_ERR_INT_ENA _M 
o UART_RS485_FRM_ERR_INT_ENA M 
o UART_RS485_ CLASH_INT_ENA_M 
o UART_AT_CMD_CHAR_DET_INT_ENA_M 

¢  rxfifo_full_ thresh 

* rx_timeout_thresh 

¢  txfifo_empty_intr_thresh 

Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_isr_free 
esp_err t uart_isr free(uart_port_t uart_num) 





Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_isr_register 
esp err t uart isr register ( 





uart_port_t uart_num, 

void (*fn) (void*), void * arg, 
int intr_alloc_ flags, 
uart_isr_ handle t *handle) 


The uart_no Is the identity of the UART being changed. It can be one of varT Num _0, 
UART_NUM_1 Of UART_NUM 2. 


Includes: 
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¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_param_config 
Configure all the parameters for a UART. 


esp err t uart param config ( 





uart_port_t uart_num, 
const uart_ config t *uart_config) 


The uart_no Is the identity of the UART being changed. It can be one of varT_Num_0, 
UART_NUM_1 Of UART_NUM_2. 


Calling this function is a convenience for setting the properties of a UART without us 
having to set the properties one by one with a stream of other calls. Here we populate a 
structure and set all the properties in one shot. 


uart_config_ t myUartConfig; 
myUartConfig.baud_rate = UART_ BITRATE 115200; 
myUartConfig.data_bits = UART_DATA 8 BITS; 

myUartConfig.parity = UART PARITY DISABLE; 
myUartConfig.stop bits = UART_STOP_ BITS 1; 


myUartConfig.flow_ ctrl = UART_HW_FLOWCTRL_ DISABLE; 
myUartConfig.rx flow _ctrl_ thresh = 120; 























Typically we would call this before installing the driver. 
Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 
uart_set_baudrate 
uart_set_word_length 
uart_set_parity 
uart_set_stop_bits 
uart_set_hw_flow_ctrl 


uart_read_bytes 
Read data from the UART. 


int uart_read_bytes ( 
uart_port_t uart_num, 
uint8 t *buf, 
uint32 t length, 
TickType t ticks to wait) 
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The uart_no Is the identity of the UART being changed. It can be one of varT Num _0, 
UART_NUM_1 Of UART_NUM_2. 


Here we read data from the UART. The maximum number of bytes we will read is 
supplied by length and buf must point to a memory buffer of at least that capacity. The 
return from the function will be the number of bytes that were actually read. We can 
also specify the number of FreeRTOS ticks to wait should no data be available. 


Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_set_baudrate 
Set the current baud rate. 


esp err t uart set baudrate( 





uart_port_t uart_no, 
uint32_ t baud_rate) 


The uart_no Is the identity of the UART being changed. It can be one of varT Num _0, 
UART_NUM_1 Of UART_NUM 2. 


The baud_rate Is the desired transmission rate in bits per second. 
Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_set_dtr 
esp err t uart set dtr ( 
uart_port_t uart_num, 





int level) 


The uart_no Is the identity of the UART being changed. It can be one of varT Num _0, 
UART_NUM_1 Of UART_NUM 2. 


Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 
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uart_set_hw_flow_ctrl 
esp err t uart set hw flow ctrl( 





uart_port_t uart_no, 
uart_hw_flowcontrol t flow ctrl, 
uint8 t rx_thresh) 


The uart_no Is the identity of the UART being changed. It can be one of varT Num _0, 
UART_NUM_1 Of UART_NUM 2. 


Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_set_line_inverse 


esp err t uart set line inverse ( 








uart_port_t uart_no, 
uint32_ t inverse mask) 


The uart_no Is the identity of the UART being changed. It can be one of varT_Num_0, 
UART_NUM_1 Of UART_NUM 2. 


Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_set_parity 
Set the parity check values. 


esp err t uart set parity( 
uart_port_t uart_no, 





uart_parity t parity mode) 


The uart_no Is the identity of the UART being changed. It can be one of varT_Num_0, 
UART_NUM_1 Of UART_NUM 2. 











The parity mode can be one of vART PARITY DISABLE, UART PARITY EVEN, 
UART_PARITY ODD. 











Includes: 
¢ #include <drivers/uart.h> 


See also: 
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uart_set_pin 
Set the pins used by this UART. 


esp err t uart set pin( 
uart_port_t uart_num, 
int tx_io_num, 





int rx_io_num, 
int rts_io_num, 
int cts_io_ num) 


The uart_no Is the identity of the UART being changed. It can be one of varT_Num_0, 
UART_NUM_1 Of UART_NUM 2. 


The tx io num is the pin number used for TX for this uart. 
The rx io num is the pin number used for RX for this uart. 


The rts_io numis the pin number used for RTS for this uart. 





The cts_io numis the pin number used for CTS for this uart. 


We can specify the value UART_PIN NO CHANGE as a value and what ever the UART 
thinks it is currently using will continue to be used. 





Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_set_rts 
esp err t uart_set_rts(uart_port_t uart_num, int level) 





The uart_no Is the identity of the UART being changed. It can be one of varT_Num_0, 
UART_NUM_1 Of UART_NUM_2. 


Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_set_stop_bits 
Set the number of data bits in the uart. 
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esp err t uart set stop bits ( 
uart_port_t uart_no, 





uart stop bits t bit num) 





The uart_no Is the identity of the UART being changed. It can be one of varT Num _0, 
UART_NUM_1 Of UART_NUM 2. 


The bit num Is the number of stop bits in effect. It can be one of varT stop BITS 1, 
UART STOP BITS 1 5 Of UART STOP BITS 2. 











Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_set_word_length 
Set the number of bits in a transmission unit. 


esp err t uart set word length ( 





uart_port_t uart_num, 
uart word length t data bit) 





The uart_no Is the identity of the UART being changed. It can be one of varT Num _0, 
UART_NUM_1 Of UART_NUM 2. 





The data_bit is the word length of a transmission. It can be one of varT DATA 5 BITS, 
UART_ DATA 6 BITS, UART DATA _7 BITS Of UART DATA 8 BITS. 








Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_tx_chars 

int uart_tx_chars ( 
uart_port_t uart_no, 
const char* buffer, 
uint32_ t len) 


The uart_no Is the identity of the UART being transmitted over. It can be one of 
UART_NUM_0, UART_NUM_1 Of UART_NUM 2. 


The buffer is a pointer to data to be transmitted. 
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The 1en is the number of bytes to transmit. 
Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_wait_tx_done 
esp err t uart wait tx done( 





uart_port_t uart_num, 
TickType t ticks to wait) 


The uart_no Is the identity of the UART being changed. It can be one of varT_Num_0, 
UART_NUM_1 Of UART_NUM 2. 


Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_write_bytes 
Write bytes through the UART. 


int uart_write bytes ( 
uart_ port _t uart_num, 
const char* src, 
size t size) 


The uart_no Is the identity of the UART being changed. It can be one of varT Num _0, 
UART_NUM_1 Of UART_NUM 2. 


Here we write data through the UART. The number of bytes to be written is specified by 
size. That number of bytes will be read starting at the memory location pointed to by 


SiECe 
Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


uart_write_bytes_with_break 
int uart write bytes with break ( 





uart_port_t uart_num, 
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const char* src, 
size t size, 
int brk_len) 


The uart_no Is the identity of the UART being changed. It can be one of varT Num _0, 
UART_NUM_1 Of UART_NUM 2. 


Includes: 
¢ #include <drivers/uart.h> 


See also: 


Working with UART/serial 


UART low level APIs 


uartAttach 


Uart_Init 


uart_div_modify 
uart_buff_switch 
uart_tx_switch 
uart_baudrate_detect 


uart_rx_one_char 
Retrieve a character from the RX FIFO buffer if one is available. 


STATUS uart_rx_one char(uint8 t *rxChar) 


Retrieve a single character from the serial input buffer. If a character was available, the 
return value is ox else it is ratL. If a character was retrieved, it will be stored in rxchar. 


Includes: 
¢ #include <rom/uart.h> 


See also: 


Working with UART/serial 
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uart_tx_wait_idle 


uart_tx_flush 
void uart_tx_flush(uint8 t uartNumber) 


uart_tx_one_char 
STATUS uart_tx_one_ char(uint8 t txChar) 


Output a char to printf channel. 
Includes: 


* rom/uart.h 


uart_tx_one_char2 


I2C APIs 
See also: 


Using the ESP-IDF I2C driver 


i2c_cmd_link_create 
Create a command handle. 


i2c cmd handle t i2c cmd link create () 





The i2c cmd handle t iS an opaque data type and should be treated as such. Think of 
a command as a "future" request to send a message over the I2C bus. Because I2C is 
timing dependent, what we want to do is first build the message we wish to send and 
then actually send it. The thinking here is that if we were to build and send 
simultaneously, any interrupts that occurred would cause timing problems. In addition, 
the ESP32 has built-in hardware support for I2C transmissions but only if we can give it 
a "unit of transmission" as an atomic operation. The high level of operation is: 


i2c_cmd_handle_t cmd = i2c_cmd_link create(); 

i2c_master start (cmd); 

i2c_ master write byte(cmd, (0x12 << 1) | I2C_ MASTER WRITE, 1 /* expect ack */); 
i2c master write byte(cmd, 0x34, 1); 




















i2c_master stop (cmd) ; 
i2c_master cmd_begin(0, cmd, 0); 
i2c_cmd_link delete (cmd) ; 


Note that we should create a cmd_handle, work with it and then delete it. Although not 
specified in the documentation, tests seem to show that once used, it should not be 
used again. 


Includes: 
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¢ #include <driver/i2c.h> 


See also: 


i2c_master_cmd_begin 
i2c_cmd_link_delete 


i2c_cmd_link_delete 
void i2c_cmd_link delete (i2c_cmd_handle t cmd_handle) 





Includes: 
¢ #include <driver/i2c.h> 


See also: 


i2c_cmd_link_create 


i2c_driver_delete 
esp_err t i2c_ driver delete(i2c_port_t i2c_num) 





The i2c_numcan be one of: 


* |2C_NUM_0 
* |2C_NUM_1 
Includes: 


¢ #include <driver/i2c.h> 


i2c_driver_install 
esp err t i2c driver install ( 





i2c_ port_t i2c_num, 
i2c_mode_t mode, 
size t slv rx buf len, 





size t slv tx buf len, 





int intr alloc flags) 
The i2c_numcan be one of: 
* I2C_NUM_0 
¢ I2C_NUM_1 
The mode can be one of: 
¢* I2C_MODE_SLAVE 
* I2C_MODE_MASTER 
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The slv_rx buf_len defines the buffer for receiving if we are a slave. 





The slv_tx buf len defines the buffer for transmitting if we are a slave. 








The intr alloc flags can be 0. 


Includes: 
¢ #include <driver/i2c.h> 


See also: 


i2c_driver_delete 
i2c_param_config 


i2c_get_data_mode 
esp err t i2c get data mode ( 





i2c_ port_t i2c_nun, 
i2c trans mode t *tx trans mode, 





i2c trans mode t *rx trans mode) 





The i2c_numcan be one of: 


* |2C_NUM_0 
* |2C_NUM_1 
Includes: 


¢ #include <driver/i2c.h> 


i2c_get_data_timing 
esp err t i2c get data timing ( 





i2c_ port_t i2c_num, 
int *sample time, 
int *hold_ time) 


The i2c_numcan be one of: 


* |2C_NUM_0O 
* |2C_NUM_1 
Includes: 


¢ #include <driver/i2c.h> 
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i2s_get_period 


esp err t i2c get period( 





i2c_ port_t i2c_num, 
int *high period, 
int *low_period) 


The i2c_numcan be one of: 


* |2C_NUM_0O 
* |2C NUM_1 
Includes: 


¢ #include <driver/i2c.h> 


i2c_get_start_timing 
esp err t i2c get start timing ( 





i2c_ port_t i2c_num, 
int *setup_time, 
int *hold_time) 


The i2c_numcan be one of: 


* |2C_NUM_0O 
* |2C NUM_1 
Includes: 


¢ #include <driver/i2c.h> 


i2c_get_stop_timing 


esp err t i2c get stop timing ( 





i2c_port_t i2c_nun, 
int *setup_time, 
int* hold_time) 


The i2c_numcan be one of: 


* |2C_NUM_0 
* |2C_ NUM_1 
Includes: 


¢ driver/i2c.h 
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i2c_isr_free 
esp err t i2c_isr free(intr_ handle t handle) 





Includes: 


¢ #include <driver/i2c.h> 


i2c_isr_register 
esp err t i2c isr register ( 





i2c_port_t i2c_nun, 

void (*fn) (void*), void * arg, 
int intr_alloc flags, 
intr_handle t *handle) 


The i2c_numcan be one of: 


* |2C_NUM_0O 
* |2C NUM_1 
Includes: 


¢ #include <driver/i2c.h> 


i2c_master_cmd_begin 
Process an I2C sequence of commands. 


esp err t i2c master cmd begin ( 





i2c_ port_t i2c_ nun, 
i2c_ cmd handle t cmd handle, 
portBASE TYPE ticks to wait) 

















The i2c_numcan be one of: 
* 1I2C_NUM_0 
* |I2C_NUM_1 


The cmd handle should be a cmd handle that has been previously created and then 
populated with the I12C commands/data to execute. 


The return codes include: 


* ESP oK (0) — Command stream processed. 





* ESP ERR INVALID ARG (0x102) — Invalid parameter. 








* ESP FAIL (-1)}- Command error; no ACK received from slave device. 





* ESP ERR INVALID STATE (0x103) — Driver not installed or not an I2C master. 


























* ESP ERR TIMEOUT (0x107) — Timed out because the bus was busy. 
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Includes: 
¢ #include <driver/i2c.h> 


See also: 


i2c_cmd_link_create 
i2c_master_write 
i2c_master_write_byte 


i2c_master_read 

Read a sequence of bytes. 

esp err t i2c master read ( 
i2c_cmd handle t cmd_ handle, 
uint8 t *data, 
size t data_len, 








int ack) 
The cmd handle is a handle that was previously created with an i2c cmd link create () 
Call. 
The data Is a buffer into which the read I2C bytes will be stored. 
The data len is the number of bytes we wish to read from the I2C. 


The ack is a flag which indicates whether or not the ESP32 should respond with an I2C 
ACK upon reading a byte. Take care here. The value 0 means DO send an ACK while 
the value 1 means DO NOT send an ACK. 


Includes: 


¢ #include <driver/i2c.h> 


i2c_master_read_byte 
Read a byte from the I2C bus. 


esp err t i2c master read byte ( 
i2c cmd handle t cmd handle, 
uint8 t *data, 
int ack) 








The cmd handle is a handle that was previously created with an i2c_ cmd link create () 
Call. 


The data Is a buffer into which the read I2C byte will be stored. 
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The ack is a flag which indicates whether or not the ESP32 should respond with an I2C 
ACK upon reading a byte. Take care here. The value 0 means DO send an ACK while 
the value 1 means DO NOT send an ACK. 


Includes: 


¢ #include <driver/i2c.h> 


i2c_master_start 
Queue command for I2C master to generate a start signal. 


esp err t i2c master start(i2c cmd handle t cmd handle) 








The start signal is used at the beginning of an I2C transmission and is followed by the 
address of the slave with which we wish to communicate. For examplem in the 
following we create a command stream, indicate that we are starting a new transaction 
and then supply the address. Note that an address is 7 bits of address data plus an 
indication of whether it is a read or write request we are making. 

i2c_cmd_handle _ t cmd = i2c_cmd_link create(); 


i2c_master start (cmd); 
i2c_ master write byte(cmd, (0x12 << 1) | I2C_MASTER WRITE, 1 /* expect ack */); 





Includes: 
¢ #include <driver/i2c.h> 


See also: 


i2c_master_cmd_begin 


i2c_master_stop 
Queue the command to indicate an I2C protocol stop. 


esp err t i2c master stop(i2c cmd handle t cmd handle) 








Includes: 


¢ #include <driver/i2c.h> 


i2c_master_write 
Write a sequence of bytes as a master. 


esp err t i2c master write ( 
i2c_ cmd handle t cmd handle, 
uint8 t *data, 
size_t data_len, 
bool ack_en) 
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The data is a pointer to the buffer of data to send. This data is not copied and must be 
preserved until after a transmission using i2c_ master cmd begin(). 


The data_ len is the length of the data to send. 


The ack_en is used to flag whether we are looking for an acknowledgment. When the 
master (the ESP32) transmits 8 bits of data, we should expect to see the slave 
acknowledge receipt. Setting the ack_en flag to true causes the driver to validate that 
the transmission worked. Setting it to false bypasses any check for an 
acknowledgment. 


Includes: 


¢ #include <driver/i2c.h> 


i2c_master_write_byte 

Write a byte as a master. 

esp err t i2c master write byte ( 
i2c_ cmd handle t cmd handle, 


uint8 t data, 
bool ack_en) 








The data Is the byte to write. 


The ack_en is used to flag whether we are looking for an acknowledgment. When the 
master (the ESP32) transmits 8 bits of data, we should expect to see the slave 
acknowledge receipt. Setting the ack_en flag to true causes the driver to validate that 
the transmission worked. Setting it to false bypasses any check for an 
acknowledgment. 


Includes: 


¢ #include <driver/i2c.h> 


i2c_param_config 
esp err t i2c param config ( 





i2c_ port_t i2c_nun, 
i2c config t *i2c conf) 





The i2c_numcan be one of: 
* 1I2C_NUM_0 
* |I2C_NUM_1 


The i2c_conf is a structure containing: 
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* i2c mode t mode — One of 
° 12C_MODE_SLAVE 
o |12C_MODE_MASTER 
* gpio_num_tsda_io num 
* gpio_pullup_tsda_pullup_en 
* gpio_num_tscl_io_num 
¢ gpio_pullup_tscl_pullup_en 
* master 
© uint32_tclk_speed 
* slave 
°o uint8 taddr_10bit_en 
° uint16 tslave_addr 
Includes: 
¢ #include <driver/i2c.h> 


See also: 


i2c_driver_install 


i2c_reset_rx_fifo 
esp_err t i2c_reset_rx fifo(i2c_port_t i2c_num) 





The i2c_numcan be one of: 


* |2C_NUM_0 
* |2C_NUM_1 
Includes: 


¢ #include <driver/i2c.h> 


i2c_reset_tx_fifo 
esp_err t i2c_reset_tx fifo(i2c_port_t i2c_num) 





The i2c_numcan be one of: 
* 1I2C_NUM_0 
¢ |I2C_NUM_1 


Page 608 


Includes: 


¢ #include <driver/i2c.h> 


i2c_set_data_mode 
esp err t i2c set data mode ( 





i2c_ port_t i2c_ nun, 
i2c trans mode t tx trans mode, 





i2Zc trans mode t rx trans mode) 





The i2c_numcan be one of: 
¢ |I2C_NUM_0 
¢ |I2C_NUM_1 


Both the tx trans mode and rx trans mode can be one of: 


¢ |2C_DATA_MODE_MSB_FIRST 
¢ |2C_DATA_MODE_LSB_ FIRST 
Includes: 


¢ #include <driver/i2c.h> 


i2c_set_data_timing 
esp err t i2c set data timing ( 
i2c_port_t i2c_num, 





int sample time, 
int hold_time) 


The i2c_numcan be one of: 


* |2C_NUM_0O 
* |2C_ NUM_1 
Includes: 


¢ #include <driver/i2c.h> 


i2c_set_period 
esp err t i2c set period( 





i2c_port_t i2c_nun, 
int high period, 
int low period) 


The i2c_numcan be one of: 
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* |2C_ NUM_0O 
* |2C_ NUM_1 
Includes: 


¢ #include <driver/i2c.h> 


i2c_set_pin 
esp err t i2c set pin( 





i2c_ port_t i2c_num, 
gpio num _t sda_io num, 





gpio num t scl io num, 





gpio pullup t sda pullup en, 





gpio pullup t scl pullup en, 





i2c_mode_t mode) 


The i2c_numcan be one of: 


* |2C_ NUM_0O 
* |2C_ NUM_1 
Includes: 


¢ #include <driver/i2c.h> 


i2c_set_start_timing 
esp err t i2c set start timing ( 





i2c_port_t i2c_ nun, 
int setup_time, 
int hold _time) 


The i2c_numcan be one of: 


* |2C_NUM_0O 
« |2C_ NUM_1 
Includes: 


¢ #include <driver/i2c.h> 


i2c_set_stop_timing 
esp err t i2c set stop timing ( 





i2c_ port_t i2c_num, 
int setup_time, 
int hold_time) 


The i2c_numcan be one of: 
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* |2C_NUM_0O 
* |2C_ NUM_1 
Includes: 


¢ #include <driver/i2c.h> 


i2c_slave_read_buffer 
int i2c_ slave read _ buffer ( 
i2c_port_t i2c_nun, 
uint8 t *data, 
size_t max_size, 
portBASE TYPE ticks _to_ wait) 











The i2c_numcan be one of: 


* |2C_NUM_0O 
* |2C NUM_1 
Includes: 


¢ #include <driver/i2c.h> 


i2c_slave_write_buffer 
int i2c_ slave write buffer ( 
i2c_port_t i2c_nun, 
uint8 t *data, 
int size, 
portBASE TYPE ticks to wait) 











The i2c_numcan be one of: 


* |2C_NUM_0O 
* |2C NUM_1 
Includes: 


¢ #include <driver/i2c.h> 


SPI APIs 


The ESP-IDF provides a driver for the SPI interface. 


See also: 


Using the ESP-IDF SPI driver 
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spi_bus_add_device 
Define a new device to SPI. 


esp err t spi bus add device ( 
spi_host_device _t host, 
spi device interface config t *dev_config, 
spi device handle t *handle) 














When we wish to interact with a device, we need to describe it to our environment. This 
returns a handle which we can subsequently use. When we no longer need the device, 
we can release resources associated with it via a call to spi_bus_ remove device(). 
Core within the characteristics that we supply with this call are the clock speed with 
which we will use when communicating and, if needed, which pin we want to use for 
slave select (CS). The queue size must also be supplied and must be at least 1. 


Host can be one of: 
¢ SPIl_HOST — Do not use. 
¢ HSPI_HOST 
¢ VSPI_HOST 
The dev_config is a structure that contains: 


* uint8 t address bits - Number of bits to send in address action (0-64). 


* uint8 t command bits — Number of bits to send in command action (0-16). 





* uint8 t dummy bits — Number of filler bits to send between address and data. 


* uint8 t mode — SPI mode (0-3) 





* uint8 t duty cycle pos — default 0. 


* uint8 t cs ena pretrans — Number of bit cycles CS should be activated before 
transmission. 





* uint8 t cs ena posttrans — Number of bit cycles CS should stay active after 
transmission. 


* int clock speed hz — Clock speed in Hz. 





* int spics io num—CS gpio pin for device or -1 if not used. 





* uint32 t flags —Bitwise OR of spr Device * flags. 
o SPI_DEVICE_TXBIT_LSBFIRST 
o SPI_DEVICE_RXBIT_LSBFIRST 
o SPI_DEVICE_3WIRE 
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o SPIl_DEVICE_POSITIVE_CS 
© SPIl_DEVICE_HALFDUPLEX 
© SPIl_DEVICE_CLK_AS CS 


* int queue size — Transaction queue size. This is the number of concurrent SPI 
requests that may be in flight at one time. It must be at least 1. 


* transaction cb t pre cb — Callback function to be invoked before a 
transmission is started. 








* transaction cb t post cb — Callback function to be invoked after a transmission 
has completed. 


The handle is the handle you can subsequently use for interacting with the device. 
Includes: 
¢ #include <driver/spi_master.h> 


See also: 


spi_bus_ initialize 
spi_bus_remove_device 


spi_bus_free 
Free up a bus. 


esp err t spi_bus_free(spi_ host device t host) 





The host can be one of: 
¢ SPIl_HOST — Do not use. 


¢ HSPIHOST 
¢ VSPILHOST 
Includes: 


¢ #include <driver/spi_master.h> 


See also: 


spi_bus_ initialize 


spi_bus_initialize 
Initialize an SPI Bus. 


esp err t spi bus initialize ( 
spi_ host _device t host, 
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spi bus config t *bus config, 





int dma_chan) 


The ESP32 provides multiple SPI bus instances. We use this API to initialize one of 
these buses. A bus is typically initialized only once during the life of an ESP32 
application. Primarily, the initialization identifies the externalized GPIO pins that will be 
used for the SPI functions core of which are CLK, MOSI and MISO. 


Host can be one of: 
¢ SPI_HOST — Do not use. Used internally. 
* HSPI_HOST 
¢ VSPIHOST 
The bus config is a structure containing: 
* int mosi_io num—GPIO for MOSI or -1 if not used. 
* int miso io num—GPIO for MISO or -1 if not used. 
* int sclk_ io num—GPIO pin for CLK or -1 if not used. 


* int quadwp_io num— Specify -1 if not used. 





* int quadhd_io num— Specify -1 if not used. 


The dma_chan is which of the two possible DMA channels to use ... either 1 or 2. 


Includes: 
¢ #include <driver/spi_master.h> 


See also: 


spi_bus_free 
spi_bus_add_device 


spi_bus_remove_device 
Release the resources of a previously registered device. 


esp err t spi bus remove device(spi device handle t handle) 











This function can be called to release the resources allocated by a previous call to 
spi_bus_add_device(). Following this call, no further transmission requests should be 
made using the now defunct handle. 


Includes: 


¢ #include <driver/spi_master.h> 
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See also: 


spi_bus_add_device 


spi_device_get_trans_result 
Retrieve results from previous queued transmissions. 


esp err t spi device get trans result ( 
spi device handle t handle, 








spi_transaction_t **trans desc, 

TickType t ticks to wait) 
When we invoke spi_device_queue_trans() we are requesting a transmission to occur 
at some time in the future. Ideally as soon as possible. This function retrieves (if 
available) the results from previously queued transmissions. 


Includes: 
¢ #include <driver/spi_master.h> 


See also: 


spi_device_queue_trans 
spi_device_transmit 


spi_device_queue_trans 
Queue a request for transmission. 


esp err t spi device queue trans ( 
spi device handle t handle, 
spi_ transaction _t *trans_ desc, 
TickType t ticks to wait) 








This function indicates that we have a transmission to be executed against an SPI 
device but that we don't need to wait for a response. Rather the request will be 
executed when it can and the response will subsequently be available for retrieval using 
the function spi_device get trans result(). 


The trans desc is a description of a transaction. It contains: 
* uint32_t flags — Bit wise OR of the spr TRans ~* flags: 
o SPIMODE_DIO 
o SPILMODE_QIO 
° SPIMODE_DIOQIO_ADDR 
o SPI_USE_RXDATA 
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o SPILUSE_TXDATA 


* uintl6 t command — Command data. Number of bits sent is defined by 
commands _bits value defined in spi device interface config t. 











* uint64 t address —Address data. Number of bits sent is defined by 
address_bits value defined in spi device interface config t. 





* size t length — Total data length to send and receive in bits. 





* size t rxlength —Length of data to receive (in bits). If 0 is supplied, then we 
use the what ever value is defined in length. 


* void *user — User defined context data. 

¢ Aunion of: 
© const void *tx buffer — Pointer to data used to hold data to be transmitted. 
© uint8 t tx data[4] — Used if SPlUSE_TXDATA is flagged. 

¢ Aunion of: 
° void *rx buffer — Pointer to data used to hold data received. 
© uint8 t rx data[4] — Used if SPlUSE_RXDATA is flagged. 

Includes: 
¢ #include <driver/spi_master.h> 


See also: 


spi_device_get_trans_result 
spi_device_transmit 


spi_device_transmit 
Perform a transmission over the SPI bus and wait for a response. 


esp err t spi device transmit ( 
spi device handle t handle, 








spi_ transaction _t *trans_ desc) 





Logically, this function is an amalgamation of esp device queue trans() followed by a 
call to spi_ device get trans result() effectively resulting in a synchronous request 
and block for response of an SPI request. 


The trans desc is a description of a transaction. It contains: 
* uint32_t flags — Bit wise OR of the SPI_TRANS * flags: 
o SPILMODE_DIO 
o SPILMODE_QIO 
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o SPI_MODE_DIOQIO ADDR 
o SPI_USE_RXDATA 
o SPI_USE_TXDATA 


uintl6 t command — Command data. Number of bits sent is defined by 
commands _bits value defined in spi device interface config t. 





uint64 t address —Address data. Number of bits sent is defined by 
address_bits value defined in spi device interface config t. 





size_t length — Total data length to send and receive in bits. Note: The size is 
in bits ... not bytes. 


size t rxlength —Length of data to receive (in bits). If 0 is supplied, then we 
use the what ever value is defined in length. 


void *user — User defined context data. 
A union otf: 


© const void *tx buffer — Pointer to data used to hold data to be transmitted. 





© uint8 t tx data[4] — Used if spr_use_txpata is flagged. 
A union of: 


© void *rx buffer — Pointer to data used to hold data received. 





© uint8 t rx data[4] — Used if sp1_usE_rxpata is flagged. 


For example: 


char data[3]; 
spi_transaction_t trans desc; 


trans desc.address = 
trans desc.command 


0 
0 
trans desc.flags = 0; 
trans desc.length = 3 

0 


trans desc.rxlength = 








trans desc.tx buffer = data; 
trans desc.rx_ buffer = data; 





data[0] = 0x12; 
data[1] = 0x34; 
data[2] = 0x56; 
ESP_ERROR_CHECK(spi_ device transmit (handle, &trans_desc)); 














Includes: 


#include <driver/spi_master.h> 
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See also: 


. spi_device_get_trans_result 
. spi_device_queue_trans 


I2S APIs 


i2s_driver_install 


esp err t i2s driver install ( 





i2s port_t 12s _num, 
const i2s config t *i2s config, 





int queue_size, 
void* 12s queue) 


i2s_driver_uninstall 
esp_err t 12s driver_uninstall(i2s port _t 12s num) 





i2s_pop_sample 
int i2s pop sample ( 
i2s port_t i2s_num, 
char *sample, 
TickType _t ticks to wait); 


i2s_push_sample 

int i2s_ push_sample ( 
i2s port_t i2s_ num, 
const char *sample, 
TickType t ticks to wait) 


i2s_read_bytes 
int i2s_ read_bytes ( 
i2s_ port_t 12s num, 
char *dest, 
size t size, 
TickType_t ticks _to_wait); 


i2s_set_pin 
esp err t i2s set pin( 
i2s port_t i2s_ num, 
const i2s pin config t *pin) 





i2s_set_sample_rates 
esp err t i2s set sample rates ( 





i2s port_t i2s_ num, 
uint32 t rate) 


i2s_start 
esp_err t 12s start(i2s port_t i2s_num) 


i2s_stop 


esp_err t 12s stop(i2s port_t i2s_ num) 
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i2s_write_bytes 
int i2s write bytes ( 
i2s port_t i2s nun, 
const char *src, 
size t size, 
TickType _t ticks to wait); 


i2s_zero_dma_buffer 
esp_err t i2s zero _dma_buffer(i2s port_t i2s_ num); 





RMT APIs 

The RMT component is the "remote" controller. The word "remote" here means a 
remote control such as you would find for controlling your TV or stereo. The primary 
function is to create complex digital wave forms that will drive infrared LEDs to generate 
a PWM signal in the infrared spectrum. However, we can attach other signal consuming 
devices to the output of this data to drive them. A good example is neopixels. 


See also: 


Remote Control Peripheral — RMT 


rmt_clr_intr_enable_mask 
Clear mask value to RMT interrupt enable register. 


void rmt_clr intr enable mask(uint32_ t mask) 





* mask — Bit mask to clear the register. 
Includes: 


¢ #include <driver/rmt.h> 


rmt_config 
esp err t rmt_config(rmt_config t* rmt_param) 





Configure an RMT channel. The rmt_param is a rich structure containing: 
* xrmt_mode (rmt_mode_t)— This can be one of 


© RMT MODE Tx — Configure this channel for output (transmission). 








© RMT MODE Rx — Configure this channel for input (reception). 


* channel (rmt_channel_t)—A value between rMT CHANNEL 0 and RMT CHANNEL 7. 
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clk div (uints t)— The clock divider value. If the base clock is 80MHz then a 
divisor of 8 gives us 10MHz, a divisor of 80 gives us 1MHz. 


gpio num (gpio num t)— The gpio number associated with the function. 


mem block num (uint8 t)—Memory block number. 


Union of 


© tx config — Configuration for transmission. 


loop en (bool) — True if loop output mode. 
carrier en (bool) —Is the carrier enabled. 
carier freq hz (uint32_t)— Carrier frequency. 
carrier_duty_percent (uints t) 

carrier_level (rmt_carrier level _t)— One of: 

¢ RMT_CARRIER_LEVEL_LOW 

* RMT_CARRIER_LEVEL_HIGH 


idle output_en (bool) — Idle level output enabled. 





idle level (rmt_idle level t)— The signal level when idle. One of: 
¢ RMT_IDLE_LEVEL_ LOW 
¢ RMT_IDLE_LEVEL_HIGH 








© xx config — Configuration information for input reception. 


Includes: 


filter en (bool) — Should signal filtering be enabled. 


filter ticks thresh (uints_t)-—lIf signal filtering is enabled, this is the 
threshold below which transitions will be ignored. 





idle threshold (uint16 t)— The duration of idleness after which the 
signal train will be considered complete. If we have a clock div of 255 (the 
maximum) and a threshold of 65535 (the maximum), this gives us a 
maximum idle period duration of about 209 msecs. 


#include <driver/rmt.h> 


rmt_driver_install 
Initialize the RMT driver. 
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esp_err t rmt_driver install ( 
rmt_channel _t channel, 
size t rx_buf size, 
int intr_alloc_ flags) 





* channel — The channel to initialize. A value between rut CHANNEL 0 and 
RMT CHANNEL 7. 





* size —The size of the RMT channel ring buffer. Can be 0. 





* intr alloc flags — Normally 0. 
Includes: 


¢ #include <driver/rmt.h> 


rmt_driver_uninstall 
Uninstall the RMT driver. 


esp err t rmt_driver uninstall (rmt_channel_t channel) 





* channel — The channel to un-install. A value between rut CHANNEL 0 and 
RMT CHANNEL 7. 








Includes: 


¢ #include <driver/rmt.h> 


rmt_fill_tx_items 

esp err t rmt fill tx items ( 
rmt_channel _t channel, 
rmt_item32_t* item, 
uintl6 t item_num, 
uintl6 t mem offset) 





* channel —Avalue between rut CHANNEL 0 and RMT CHANNEL_7. 








* item-— Pointer to items. 





* item _num— Number of items. 
* mem offset — Offset into memory 
Includes: 


¢ #include <driver/rmt.h> 
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rmt_get_clk_div 
Get the RMT clock divider. 
esp err t rmt_ get clk div( 


rmt_channel _t channel, 
uint8 t* div_cnt) 











* channel —Avalue between rmT CHANNEL 0 and RMT CHANNEL_7. 

* div cnt — The divider of the base clock which is 80MHz. 
Includes: 

¢ #include <driver/rmt.h> 


See also: 


rmt_set_clk_div 


rmt_get_mem_block_num 
Get the number of memory blocks used by this channel. 


esp err t rmt get mem block num( 





rmt_channel _t channel, 
uint8 t* rmt_mem_num) 


* channel —Avalue between rmT CHANNEL 0 and RMT CHANNEL_7. 








* rmt_mem_num—A Storage area that will be used to hold the number of memory 
blocks allocated to the channel. 


Includes: 
¢ #include <driver/rmt.h> 


See also: 


rmt_set_mem_block_num 


rmt_get_mem_pd 
Get memory low power mode. 


esp err t rmt_get_mem pd(rmt_channel t channel, bool* pd_en) 





* channel —Avalue between rmT CHANNEL 0 and RMT CHANNEL_7. 








* pd _en—Pointer to receive the memory low power mode. 
Includes: 


¢ #include <driver/rmt.h> 
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rmt_get_memory_owner 
Ge the memory owner of a channel's memory block. 


esp err t rmt get memory owner ( 





rmt_channel _t channel, 
rmt_mem_owner t* owner) 


* channel —Avalue between rmT CHANNEL 0 and RMT CHANNEL_7. 





* owner —A storage area that will be filled in with the owner 
One of: 








© RMT MEM OWNER TX 

















© RMT MEM OWNER RX. 


Includes: 


¢ #include <driver/rmt.h> 


rmt_get_ringbuf_handler 
Get the ring-buffer handler. 
esp_err t rmt_get_ringbuf_handler ( 


rmt_channel_t channel, 
RingbufHandle t *buf_handle) 








* channel —Avalue between RMT CHANNEL 0 and RMT CHANN 
* buf handle —Ahandle to the ring buffer. 

Includes: 
¢ #include <driver/rmt.h> 


¢ #include <freertos/ringbuf.h> 


rmt_get_rx_idle_thresh 
Get RMT idle threshold. 


esp_err t rmt_get_rx_idle thresh(rmt_channel _t channel, uintl6_ 








of the memory block. 





Bla 


t *thresh) 





* channel —Avalue between rut CHANNEL 0 and RMT CHANNEL_7. 





* thresh —A pointer to storage into which the RX idle threshold will be copied. 


Includes: 


¢ #include <driver/rmt.h> 
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rmt_get_status 
Get RMT status. 


esp err t rmt_get_status(rmt_channel_t channel, uint32 t* status) 





* channel 
* status 
Includes: 


¢ #include <driver/rmt.h> 


rmt_get_source_clk 
Get the source clock. 


esp err t rmt get source clk( 





rmt_channel _t channel, 


rmt source clk t* src clk) 











* channel —Avalue between RMT CHANNEL 0 and RMT CHANN 


> Soe 


(eo) 


ie) 


Includes: 


RM1 


RM1 


1k — The source of the clock. One of: 





[ BASECLK REF —A 1MHz clock (not supported). 


[ BASECLK APB — The APB clock at 80MHz. 




















¢ #include <driver/rmt.h> 


rmt_get_tx_loop_mode 
Get tx loop mode. 


esp err t rmt get tx loop mode ( 





rmt_channel_t channel, 


bool* loop en) 





Bi 





* channel —Avalue between RMT CHANNEL 0 and RMT CHANW 


EL 7. 


* loop en— The current value of the loop transmission state. 


Includes: 


¢ #include <driver/rmt.h> 


See also: 


rmt_set_tx_loop_mode 
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rmt_isr_deregister 
De-register a previously registered interrupt handler. 


esp_err t rmt_isr deregister(rmt_isr handle t handle) 





* handle —Ahandle returned from a previous call to rmt_isr register(). 
Includes: 
¢ #include <driver/rmt.h> 


See also: 


rmt_isr_register 


rmt_isr_register 
Handler for ISR. 


esp err t rmt_isr register ( 
void (*fn) (void *), void * arg, int intr alloc flags, rmt_isr handle t *handle) 





¢ f£n—A function to be called when an interrupt occurs. 
* arg —Parameters/context for the interrupt handler 


* intr alloc flags — Interrupt allocation flags. 





* handle —Ahandle returned used to refer to this registered interrupt handler. 


The signature of the handler function is: 


void func(void *args) 
Includes: 
¢ #include <driver/rmt.h> 


See also: 


rmt_isr_deregister 
rmt_clr_intr_enable_mask 
rmt_set_err_intr_en 
rmt_set_intr_enable_mask 
rmt_set_rx_intr_en 
rmt_set_tx_thr_intr_en 


rmt_memory_rw_rst 
Reset TX/RX memory index. 


esp err t rmt_memory rw_rst(rmt_channel _t channel) 
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* channel —Avalue between RMT CHANNEL 0 and RMT _CHANN 








Includes: 


¢ #include <driver/rmt.h> 


rmt_rx_start 
Start receiving data. 


esp err t rmt_rx_start(rmt_channel_t channel, bool rx_idx_ rst) 











* channel —Avalue between rmT CHANNEL 0 and RMT CHANW 
* rx idx rst — Set to true to reset the receiver index. 
Includes: 


¢ #include <driver/rmt.h> 


rmt_rx_stop 
Stop receiving data. 


esp err t rmt_rx_stop(rmt_channel t channel) 








* channel —Avalue between RMT CHANNEL 0 and RMT CHANN 
Includes: 


¢ #include <driver/rmt.h> 


rmt_set_clk_div 
Set RMT clock divider. 


esp err t rmt set clk div( 





rmt_channel_t channel, 
uint8 t div_cnt) 





* channel —Avalue between RMT CHANNEL 0 and RMT CHANW 
* div cnt —RMT counter clock divider. 

Includes: 
¢ #include <driver/rmt.h> 


See also: 


rmt_get_clk_div 
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EL 7. 


Bl 7 





EL 7. 





Bis I, 


rmt_set_err_intr_en 


esp err t rmt_set_err intr _en(rmt_channel_t channel, bool en) 





Includes: 


¢ #include <driver/rmt.h> 


rmt_set_idle_level 

esp err t rmt set idle level ( 
rmt_channel _t channel, 
bool idle out_en, 
rmt_idle level t level) 








* idle out _en— Should an idle level be set. 


* level — The idle level. One of: 





© RMT IDLE LEVEL Low — The value for a low level. 
































© RMT IDLE LEVEL HIGH — The value for a high level. 
Includes: 


¢ #include <driver/rmt.h> 


rmt_set_intr_enable_mask 
void rmt_set_intr enable mask(uint32_t mask) 





Includes: 


¢ #include <driver/rmt.h> 


rmt_set_mem_block_num 
Set the number of adjacent memory blocks used by the channel. 


esp err t rmt set mem block num( 
rmt_channel t channel, 
uint8 t blockCount) 











* channel —Avalue between rut CHANNEL 0 and RMT CHANNEL_7. 


* blockCount — The number of memory blocks associated with the channel. 
Between 1 and 8. 


Includes: 


¢ #include <driver/rmt.h> 
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See also: 


rmt_get_mem_block_num 


rmt_set_mem_pd 
Set RMT memory in low power mode. 


esp err t rmt_set_mem _pd(rmt_channel t channel, bool pd_en) 





Includes: 


¢ #include <driver/rmt.h> 


rmt_set_memory_owner 
Set the memory owner of a channels memory block. 


esp err t rmt_ set memory owner ( 





rmt_channel _t channel, 
rmt_mem_owner t owner) 


* channel — The type of owner of the memory block associated with the channel. 








* owner — One of RMT MEM OWNER TX Of RMT MEM OWNER RX. 




















Includes: 


¢ #include <driver/rmt.h> 


rmt_set_pin 
esp err t rmt_ set pin( 





rmt_channel _t channel, 
rmt_mode_t mode, 
gpio_num_t gpio_ num) 








* channel —A value between rMT_CHANNEL_0 and RMT_CHANNEL_7. 
* node 
* gpio_num 

Includes: 


¢ #include <driver/rmt.h> 


rmt_set_rx_filter 
esp err t rmt set rx filter ( 





rmt_channel _t channel, 
bool rx filter _en, 
uint8 t thresh) 
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* channel —Avalue between rmT CHANNEL 0 and RMT CHANNEL 7. 
* rx filter _en-—true to enable input filtering and false to disable. 


* thresh — The threshold in clock ticks below which incoming signals should be 
discarded. 


Includes: 


¢ #include <driver/rmt.h> 


rmt_set_rx_idle_thresh 
Se the RMT RX idle threshold. 


esp err t rmt set rx idle thresh ( 





rmt_channel _t channel, 
uintl6 t thresh) 


* channel —Avalue between rmT CHANNEL 0 and RMT CHANNEL_7. 








* thresh — The value in clocks ticks where the lack of a transition indicates a return 
to idle mode. 


Includes: 
¢ #include <driver/rmt.h> 


See also: 


rmt_get_rx_idle_thresh 


rmt_set_rx_intr_en 
Enable or disable an interrupt for having received a signal train. 


esp err t rmt_set_rx_intr_en(rmt_channel t channel, bool en) 











* channel —Avalue between rmT CHANNEL 0 and RMT CHANNEL 7. 
¢ en— True to enable the interrupt, false to disable. 
Includes: 


¢ #include <driver/rmt.h> 


rmt_set_tx_carrier 


esp err t rmt set tx carrier ( 





rmt_channel _t channel, 
bool carrier _en, 
uintl6 t high level, 
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uintl6 t low_level, 
rmt_carrier level _t carrier level) 


Includes: 


¢ #include <driver/rmt.h> 


rmt_set_tx_intr_en 
esp err t rmt set tx intr en( 





rmt_channel _t channel, 
bool en) 


Includes: 
¢ #include <driver/rmt.h> 


See also: 


rmt_set_err_intr_en 
rmt_set_rx_intr_en 
rmt_set_tx_thr_intr_en 


rmt_set_tx_loop_mode 

esp err t rmt set tx loop mode ( 
rmt_channel _t channel, 
bool loop _en) 





Includes: 
¢ #include <driver/rmt.h> 


See also: 


rmt_get_tx_loop_mode 


rmt_set_tx_thr_intr_en 
esp err t rmt set tx thr intr en en( 





rmt_channel _t channel, 
bool en, 
uintl6 t evt_thresh) 


Includes: 


¢ #include <driver/rmt.h> 


rmt_set_source_clk 
Set the reference source clock. 
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esp err t rmt set source clk( 
rmt_channel _t channel, 
rmt source clk t base clk) 











* channel —Avalue between rmT CHANNEL 0 and RMT CHANNEL 7. 








* base clk — The source of the clock. One of: 








© RMT BASECLK_ REF —A 1MHz clock (not supported). 


© RMT BASECLK APB — The APB clock at 80MHz. 

















Includes: 


¢ #include <driver/rmt.h> 


rmt_tx_start 
Start the channel transmitting. 
esp err t rmt tx start ( 


rmt_channel _t channel, 
bool tx_idx rst) 





* channel — The channel to start transmitting upon. 


* tx idx rst —If true, the transmission will start at 1° memory block otherwise it 
will continue from where it was last stopped. 


Includes: 


¢ #include <driver/rmt.h> 


rmt_tx_stop 
Stop the channel transmitting. 


esp err t rmt_tx_stop(rmt_channel t channel) 





* channel — The channel to stop transmitting. 
Includes: 


¢ #include <driver/rmt.h> 


rmt_wait_tx_done 
esp_err t rmt_wait_tx_done(rmt_channel_t channel) 





Includes: 


¢ #include <driver/rmt.h> 
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rmt_write_items 
Send wave forms. 
esp err t rmt write items ( 


rmt_channel _t channel, 
rmt item32 t* rmt item, 








int item_num, 
bool wait _tx_done) 





* channel — The channel to transmit upon. A value between rut CHANNEL 0 and 
RMT CHANNEL 7. 





* xrmt_item—An array of items to transmit. This is a data type that is a union 
between: 


© uint32 t val — The value of an item as a whole. 

© structure of: 
= uint32 t durationo — The duration of the 1“ part of the item. 
= uint32 t levelo—The signal level of the 1* part of the item. 


™ uint32 t duration1 — The duration of the 2™ part of the item. 








= uint32 t levell — The signal level of the 2™ part of the item. 
* item num — Number of items to transmit. 
* wait tx done —If true, will wait for transmission to complete. 


It is vital to note that the array of items passed in is not copied. Instead the data is used 
for the duration of the writing. As such one can't release or otherwise modify the data 
until after the write is complete. 


Includes: 


¢ #include <driver/rmt.h> 


LEDC/PWM APIs 
This section discusses the driver APIs for the LEDC / PWM access. 


See also: 


Pulse Width Modulation - PWM 


ledc_bind_channel_timer 
esp_err t ledc_bind_channel_ timer ( 
ledc_mode_t speedMode, 
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uint32 t channel, 
uint32 t timerIdx) 


Currently, speedMode can only be LEDC _HIGH SPEED MODE. 





























The channel can be one LED CHANNEL 0 — LEDC_CHANNEL_7. 











Includes: 


#include <driver/ledc.h> 


ledc_channel_config 
Configure a PWM channel. 


esp_err t ledc_ channel config ( 
ledc_channel config t *ledcConf) 


The ledccon¢f structure contains: 


gpio_num— The GPIO pin upon which the signal will appear. 
speed_mode — One of: 

o LEDC_HIGH_SPEED_MODE 

channel — One of: 

o LEDC _CHANNELO — LEDC_CHANNEL7 

intr type — One of: 

o LEDC_INTR_DISABLE 

o LEDC_INTR_FADE_END 

timer sel — One of: 

o LEDC_TIMERO — LEDC_TIMER_3 


duty — Duty range. The duration of the high signal within any given period. The 
value is specified as the value of the timer after which the signal will drop low. 
Note that the granularity of a timer is specified when the timer is configured and 
can be between 10 and 15 bits. The "speed' of increments is defined by the 
frequency property of the timer. 


Includes: 


#include <driver/ledc.h> 


See also: 


ledc_timer_config 
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ledc_fade_func_install 





sp_err t ledc_fade func _install(int intr alloc flags) 





Includes: 


¢ #include <driver/led 


ledc_fade_start 
esp err t ledc fade start ( 





ledc_channel t channel, 


c.h> 


ledc fade mode t wait done) 





Includes: 


¢ #include <driver/led 


ledc_fade_func_uninstal 


c.h> 


l 


void ledc_fade_ func_uninstall() 


Includes: 


¢ #include <driver/led 


ledc_get_duty 


c.h> 


Get the duty value for the channel. 


int ledc_get_duty ( 
ledc_mode_t speedMode, 
ledc_channel t channel) 





Currently, speedMode can only be LEDC _HIGH SPEED MODE. 


The channel can be one 11 
Includes: 
¢ #include <driver/led 


See also: 


ledc_set_duty 
ledc_channel_config 
ledc_update_duty 


ledc_get_freq 
Get the frequency for the t 
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ED CHANNEL 0 — LEDC_CHANNI 














c.h> 


imer. 


stg 


uint32 t ledc_get_freq( 
ledc_mode_t speedMode, 
ledc_timer t timerNum) 


Currently, speedMode Can only be 1: 
The timerNum can be one of: 

* LEDC_TIMER_0O 

* LEDC_TIMER_1 

¢ LEDC_TIMER_2 

¢ LEDC_TIMER_3 
Includes: 


¢ #include <driver/ledc.h> 


ledc_set_duty 
Set the duty value for the channel. 





sp err t ledc set duty( 
ledc_mode_t speedMode, 





ledc_channel t channel, 
uint32 t duty) 


Currently, speedMode Can only be 1: 





The channel can be one LED CHANNEL 0 — LEDC_CHANNI 


The duty value is set as a function of the number of bits set for the channel. 


Includes: 


¢ #include <driver/ledc.h> 


See also: 


ledc_update_duty 
ledc_channel_config 
ledc_get_duty 


ledc_isr_register 
Register an ISR. 


esp err t ledc isr register ( 





uint32 t ledc_intr_num, 
void (*fn) (void *), void *arg) 





EDC HIGH SP 











KED MODE. 














EDC HIGH SP 











KED MODE. 























ligt 
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Include 


¢ #include <driver/ledc.h> 


Ss: 


ledc_set_fade 
Set the fade value. 





sp err t ledc set fad 





( 


ledc_mode_t speedMode, 
uint32_ t channel, 
uint32 t duty, 

ledc_duty duration _t graduleDirection, 
uint32_ t stepNum, 
uint32 t dutyCycleNum, 
uint32_ t dutyScale) 


Currently, speedMode can only be LEDC _HIGH SPEED MODE. 























The channel Is the channel against which we are setting the fading. 


The duty Is the start value of the duty against which we will then fade. 


The graduleDu 











EDC DUI 





The dui 


tyScal 





The dui 





tyCycl 


rY DIR _D 


ration Is the direction of the fade. It may be one of: 





EDC DUTY DIR INCRE 


AS 


= — Increase the duty value over time. 














E.CRE 


iAS 





: — Decrease the duty value over time. 





|e is the amount that the duty value is changed each cycle. 


|eNum is the number of clock cycles that pass before the duty value of the 


channel is changed by the dutyScale amount. 


The stepNum is the count of the number of times the duty value will change before the 
fade cycle is considered complete. 


Includes: 


¢ #include <driver/ledc.h> 


ledc_set_fade_with_step 





sp err t ledc set fad 


with step ( 





ledc_mode_t speed mode, 
ledc_channel t channel, 





int target duty, 


int 


scale, 


int cycle num) 


Currently, speedMode Can only be LEDC _HIGH SPEED MODE. 


The channel can be one 11 
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ED CHANNEL 0 — LEDC_CHANNEL_7. 














Includes: 


¢ #include <driver/ledc.h> 


ledc_set_fade_with_time 
Fade from current value to target valie. 


sp err t ledc set fade with time ( 
ledc_mode_t speed mode, 











ledc_channel t channel, 
int target duty, 
int max fade time ms) 





Currently, speedMode can only be LEDC HIGH SP 








EED MODE. 














The channel can be one LED CHANNEL 0 — LEDC_CHANNEL_7. 

















The target duty Is the target duty value we want to reach relative to the current value. 





The max fade time ms is the time it should take us to reach the duty value. 


Includes: 


¢ #include <driver/ledc.h> 


ledc_set_freq 
Set the frequency for the timer. 





sp err t ledc set freq( 





ledc_mode_t speedMode, 
ledc_timer t timerNum, 
uint32_ t freqHz) 


Currently, speedMode can only be LEDC HIGH SP 











EED MODE. 














The timerNum can be one of: 
¢« LEDC_TIMER_0O 
* LEDC_TIMER_1 
¢ LEDC_TIMER_2 
¢ LEDC _TIMER_3 
Includes: 


¢ #include <driver/ledc.h> 


Page 637 


ledc_stop 
Halt the PWM signal output. 


esp err t ledc_stop( 
ledc_mode_t speedMode, 
ledc_channel t channel, 
uint32 t idleLevel) 





Currently, speedMode can only be LEDC _HIGH SPEED MODE. 



































The channel can be one LED CHANNEL 0 — LEDC_CHANNEL_7. 
Includes: 


¢ #include <driver/ledc.h> 


ledc_timer_config 
Configure a timer. 





sp err t ledc timer config ( 





ledc timer config t *timerConf) 





The timerConf is a pointer to a structure containing: 
* ledc_mode_t speed_mode — Can be one of: 


o LEDC_HIGH SPEED MODE 





* ledc timer bit t bit num—Can be one of: 








© LEDC TIMER 10 BIT— 0-1023 








© LEDC TIMER 11 BiT—O-2047 


© LEDC TIMER 12 BriT—0-4095 





© LEDC TIMER 13 BIT—O-8191 


© LEDC TIMER 14 BIT—0-16383 
© LEDC TIMER 15 BIT —O0-32767 






































* lede timer t timer num— Can be one of: 
o LEDC_TIMER_0O 
o LEDC_TIMER_1 
o LEDC_TIMER_2 
o LEDC_TIMER_3 
* uint32 t freq hz— The frequency of the signal in Hz. 


Includes: 
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¢ #include <driver/ledc.h> 


See also: 


Pulse Width Modulation — PWM 
ledc_channel_config 


ldec_timer_pause 
Pause the timer. 





sp err t ledc timer pause ( 








ledc_mode_t speedMode, 
uint32 t timerSel) 





Currently, speedMode can only be LEDC _HIGH SPEED MODE. 




















Includes: 


¢ #include <driver/ledc.h> 


ledc_timer_resume 
Resume the timer. 





sp err t ledc timer resume ( 








ledc_mode_t speedMode, 
uint32 t timerSel) 





Currently, speedMode Can only be LEDC _HIGH SPEED MODE. 




















Includes: 


¢ #include <driver/ledc.h> 


ledc_timer_rst 
Reset the timer. 





sp err t ledc timer rst ( 





ledc_mode_t speedMode, 
uint32 t timerSel) 




















Currently, speedMode can only be LEDC _HIGH SPEED MODE. 





Includes: 


¢ #include <driver/ledc.h> 
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ledc_timer_set 
Explicitly set the timer details. 





sp err t ledc timer set ( 
ledc_mode_t speedMode, 
ledc_timer t timerSel, 
uint32 t divNum, 
uint32 t bitNum, 
lede_clk_sre_t clkSrc) 








Currently, speedMode Can only be LEDC _HIGH SPEED MODE. 




















The timerSel can be one of: 
¢ LEDC_TIMER_0O 
* LEDC_TIMER_1 
¢ LEDC_TIMER_2 
¢ LEDC _TIMER_3 
Includes: 


¢ #include <driver/ledc.h> 


ledc_update_duty 
Update the duty value or the fade parameters for the channel. 
esp err t ledc update duty ( 


ledc_mode_t speedMode, 
ledc_channel _t channel) 











Currently, speedMode can only be LEDC _HIGH SPEED MODE. 



































The channel Can be one LED CHANNEL _0 — LEDC_CHANNEL_7. 
Includes: 
* #include <driver/ledc.h> 


See also: 


ledc_get_duty 
ledc_set_duty 
ledc_channel_config 


Pulse Counter 


pcnt_counter_clear 
esp err t pent counter clear(pcent_unit_t pcnt_unit) 
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pcnt_counter_pause 
esp err t pent_counter pause(pcnt_unit_t pent_unit) 


pcnt_counter_resume 
esp err t pent _counter resume(pcnt_unit_t pcnt_unit) 


pcnt_event_disable 

esp err t pent event disable ( 
pent_unit_t unit, 
pent evt type t evt type) 











pcnt_event_enable 

esp err t pcnt event enable ( 
pent_unit_t unit, 
pent evt type t evt type) 











pcnt_filter_enable 
esp err t pent _filter enable(pcnt_unit_t unit) 





pcnt_filter_disable 


esp err t pent filter disable(pcnt_unit_t unit) 





pcnt_get_counter_value 

esp err t pent _get_counter value ( 
pent_unit_t pent_unit, 
intl6 t* count) 





pcnt_get_event_value 

esp err t pent get event value ( 
pent_unit_t unit, 
PCnt eve. type. tC: eve type, 
intl6 t *value) 
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pcnt_get_filter_value 

esp err t pent get filter value( 
pent_unit_t unit, 
uintl6 t *filter val) 








pcnt_intr_enable 
esp err t pent_intr enable(pcnt_unit_t pent_unit) 





pcnt_intr_disable 
esp err t pent_intr disable(pcnt_unit_t pcnt_unit) 





pcnt_isr_register 

esp err t pent isr register ( 
uint32_ t pcnt_intr_num, 
void (*fn) (void*), void * arg) 





pcnt_set_event_value 

esp err t pent set event value ( 
pent_unit_t unit, 
pent evt. type tL -evc. type; 
intl6 t value) 











pcnt_set_filter_value 

esp err t pent set filter value( 
pent_unit_t unit, 
uintl6 t filter val) 








pcnt_set_mode 

esp err t pcnt set mode( 
pent_unit_t unit, 
pcent_channel_t channel, 





pcnt count mode t pos mode, 
pent count mode t neg mode, 
pent_ctrl_mode_t hctrl_ mode, 
pent_ctrl_mode_t lctrl_ mode) 








pcnt_set_pin 


esp err t pent_set_pin(pcnt_unit_t unit, pent channel t channel, 





ctrl_io) 
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int pulse io, 


int 


pcnt_uint_config 
esp_err t pent_unit_config(pcent_config t *pcent_config) 





Logging 
ESP-IDF provides a set of logging functions primarily used for debugging. The primary 
include file is called "esp log.h". 


esp_log_level_set 
Set the log level for the specified tag. 


void esp log level set( 

const char *tag, 

esp_log level t level) 
The tag is the identifier for the class of logging. The value "*" resets all tags to the 
specified log level. 


The level is the level of logging at or above that will be included in the log output. It may 
be one of: 





* ESP LOG VERBOSE — Log at the verbose level. 








* ESP _LOG DEBUG — Log at the debug level. 








* ESP LOG INFO —Log at the information level. 





* ESP LOG WARN — Log at the warning level. 








* ESP _LOG ERROR —Log at the error level. 




















* ESP LOG NONE — No logging. 
Includes: 
¢ #include <esp_log.h> 


See also: 


ESP-IDF logging 


esp_log_set_vprintf 
Specify a function that will be used to output the log data. 


void esp_log_set_vprintf(vprintf like t func) 


By default, the output of logging is sent to the UART but we may wish to perform other 
tasks such as a circular log in memory or writing to a storage device or sending over a 
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TCP/IP socket. By providing our own function here, we can control the output 
destination and event tinker with the format (if needed). 


Includes: 
¢ #include <esp_log.h> 


See also: 


ESP-IDF logging 


esp_log_write 
Write an entry to the output log. 


void esp log write ( 
esp_log level _t level, 


const char *tag, 
const char *format, ....) 


The level is the level of this log record being written. It may be one of: 





* ESP LOG VERBOSE — Log at the verbose level. 











* ESP LOG DEBUG —Log at the debug level. 





* ESP LOG INFO —Log at the information level. 





* ESP LOG WARN — Log at the warning level. 





* ESP _LOG ERROR —Log at the error level. 

















* ESP LOG NONE — No logging. 








The tag is the identifier for this tag of log and format is the specification of what is to be 
written. Ideally we shouldn't call this function directly but instead use of the logging 
macros such aS ESP _LOGV(tag, format, ..). 





Includes: 
¢ #include <esp_log.h> 


See also: 


ESP-IDF logging 


Non Volatile Storage 
The non-volatile storage components save and load data from storage that is preserved 
between boots. 


See also: 


Non Volatile Storage 
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nvs_close 
Close a previously opened handle. 


void nvs_close(nvs_handle handle) 


Close a handle that was previously opened by a call to nvs_open(). Remember that 
updates to the store are not completed until after a call to nvs_commit(). Closing a 
handle without performing a commit will discard any changes. 


Includes: 
¢ #include <nvs.h> 


See also: 


nvs_open 


nvs_commit 
Commit changes to non volatile storage. 


esp err t nvs_commit(nvs_handle handle) 


Any writes made against the storage are committed at this point. Note that writes may 
have been committed before this point but this forces all the writes to be flushed. Think 
of this as committing any pending writes as opposed to anything related to a 
transaction. 


Includes: 


¢ #include <nvs.h> 


nvs_erase_all 
Erase all the name value pairs. 


esp err t nvs_erase _all(nvs_handle handle) 





Erase all the name value pairs. Note that this may not be truly performed until after a 
Call to nvs_commit(). 


Includes: 
¢ #include <nvs.h> 


See also: 


nvs_commit 
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nvs_erase_key 
Erase a specific name/value key pair. 


esp err t nvs erase key ( 





nvs_handle handle, 
char *key) 


Erase the name/value pair with the given key. The deletion may not truly occur until 
after an associated commit is made. 


Includes: 
¢ #include <nvs.h> 


See also: 


nvs_commit 


nvs_flash_init 
Initialize NVS with defaults. 


esp err t nvs flash init (void) 





The defaults as of 2016-10 are a 12KByte area starting at 0x0000 6000 in flash offset. 
This is 0x0000 6000 to 0x0000 8FFF (by offsets). 


Includes: 


¢ #include <nvs_flash.h> 


nvs_flash_init_custom 
Custom initialize NVS. 


esp err t nvs flash init custom ( 





uint32_ t baseSector, 
uint32_ t sectorCount) 


Includes: 


¢ #include <nvs_flash.h> 


nvs_get_blob 
Retrieve a blob of data from storage. 


esp err t nvs get blob( 





nvs_handle handle, 
const char *key, 
void *out, 

size_t *length) 
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The out is a pointer to the storage that will be used to hold the retrieved data. On input 
length holds the size of the storage available to hold the result and will be updated with 
the actual length retrieved. 


If out has a NULL value then the length that is needed to be allocated to hold the data is 
returned in length. 


The return value is ESP_OK on success and an indication code on error. Common 
codes include: 





* ESP ERR NVS NOT FOUND — Key not found. 














Includes: 


¢ #include <nvs.h> 


nvs_get_str 
Retrieve a null terminated string from storage. 


esp err t nvs_ get str ( 





nvs_handle handle, 

const char *key, 

char *out,; 

size t *length) 
The out is a pointer to the storage that will be used to hold the retrieved data. On input 
length holds the size of the storage available to hold the result and will be updated with 
the actual length retrieved. 


If out has a NULL value then the length that is needed to be allocated to hold the data is 
returned in length. This includes the NULL byte terminator. 


The return value is ESP_OK on success and an indication code on error. Common 
codes include: 





* ESP ERR NVS NOT FOUND — Key not found. 














Includes: 


¢ #include <nvs.h> 


nvs_get_i8 
Retrieve an 8 bit integer. 


esp err t nvs get i8( 





nvs_handle handle, 
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const char *key, 
int8 t *out_value) 


The return value is ESP_OK on success and an indication code on error. Common 
codes include: 





* ESP ERR NVS NOT FOUND — Key not found. 














Includes: 


¢ #include <nvs.h> 


nvs_get_i16 
Retrieve a 16 bit integer. 


esp err t nvs_ get i16( 





nvs_handle handle, 

const char *key, 

intl6é t *out_value) 
The return value is ESP_OK on success and an indication code on error. Common 
codes include: 





* ESP ERR NVS NOT FOUND — Key not found. 














Includes: 


¢ #include <nvs.h> 


nvs_get_i32 
Retrieve a 32 bit integer. 


esp err t nvs_ get i132 ( 





nvs_handle handle, 

const char *key, 

int32_ t *out_value) 
The return value is ESP_OK on success and an indication code on error. Common 
codes include: 





* ESP ERR NVS NOT FOUND — Key not found. 














Includes: 


¢ #include <nvs.h> 


nvs_get_i64 
Retrieve a 64 bit integer. 
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esp err t nvs_ get i64( 





nvs_handle handle, 

const char *key, 

int64 t *out_value) 
The return value is ESP_OK on success and an indication code on error. Common 
codes include: 





* ESP ERR NVS NOT FOUND — Key not found. 














Includes: 


¢ #include <nvs.h> 


nvs_get_u8 
Retrieve an unsigned 8 bit integer. 


esp err t nvs get u8 ( 





nvs_handle handle, 

const char *key, 

uint8 t *out_value) 
The return value is ESP_OK on success and an indication code on error. Common 
codes include: 





* ESP ERR NVS_NOT FOUND — Key not found. 














Includes: 


¢ #include <nvs.h> 


nvs_get_u16 
Retrieve an unsigned 16 bit integer. 


esp err t nvs get ul6é( 





nvs_handle handle, 

const char *key, 

uintl6 t *outValue) 
The return value is ESP_OK on success and an indication code on error. Common 
codes include: 





* ESP ERR NVS NOT FOUND — Key not found. 














Includes: 


¢ #include <nvs.h> 
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nvs_get_u32 
Retrieve an unsigned 32 bit integer. 


esp err t nvs_ get u32 ( 





nvs_handle handle, 

const char *key, 

uint32 t *outValue) 
The return value is ESP_OK on success and an indication code on error. Common 
codes include: 














* ESP ERR NVS NOT FOUND — Key not found. 





Includes: 


¢ #include <nvs.h> 


nvs_get_u64 
Retrieve an unsigned 64 bit integer. 


esp err t nvs_ get u64( 





nvs_handle handle, 

const char *key, 

uinte4 t *outValue) 
The return value is ESP_OK on success and an indication code on error. Common 
codes include: 














* ESP ERR NVS NOT FOUND — Key not found. 





Includes: 


¢ #include <nvs.h> 


nvs_open 
Open a storage area with a given namespace. 


esp err t nvs_open( 
const char *name, 





nvs_open_mode open mode, 
nvs_handle *outHandle) 


Open a given named storage area for access. The name of the area is supplied in the 
name parameter. The open mode may be one of: 


* NVS READWRITE — The application can read and write the storage. 








* NVS READONLY — The application can only read the storage. 


The outHandle Is a pointer to storage where a handle will be stored. This is the handle 
passed into other NVS API calls. 
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If the call succeeded, EspP_ox will be returned. Otherwise other codes such as: 





* ESP _ERR_NVS NOT FOUND — Namespace doesn't exist and opened read-only. 














For example: 


nvs_handle handle; 








nvs_open("namespace", NVS_READWRITE 








nvs_ close (handle) ; 
Includes: 
¢ #include <nvs.h> 


See also: 


nvs_close 


nvs_set_blob 


Save a blob of data to storage. The maximum size is 4000 bytes per blob. 


esp err t nvs_ set blob( 
nvs_handle handle, 
const char *key, 





const void *value, 
size_t length) 


Includes: 
¢ #include <nvs.h> 


See also: 


nvs_commit 


nvs_set_str 
Save a null terminated string. 


esp err t nvs set str( 
nvs_handle handle, 





const char *key, 
const char *value) 


The key is the key against which the string will be saved. 


The value is the value to save. 
Includes: 
¢ #include <nvs.h> 


See also: 


, 


&handle) ; 
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nvs_commit 


nvs_set_i8 
Save an 8 bit integer. 


esp err t nvs_ set i8( 
nvs_handle handle, 





const char *key, 
int8 t value) 


Includes: 
¢ #include <nvs.h> 


See also: 


nvs_commit 


nvs_set_i16 
Save a 16 bit integer. 


esp err t nvs set i16( 
nvs_handle handle, 





const char *key, 
intl6 t value) 


Includes: 
¢ #include <nvs.h> 


See also: 


nvs_commit 


nvs_set_i32 
Save a 32 bit integer. 


esp err t nvs set 132 ( 
nvs_handle handle, 





const char *key, 
int32_t value) 


Includes: 
¢ #include <nvs.h> 


See also: 


nvs_commit 


nvs_set_i64 
Save a 64 bit integer. 
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esp err t nvs set i164 ( 
nvs_handle handle, 





const char *key, 
int64 t value) 


See also: 


nvs_commit 


nvs_set_u8 
Save an unsigned 8 bit integer. 


esp err t nvs_ set u8( 
nvs_handle handle, 





const char *key, 
uint8 t value) 


Includes: 
¢ #include <nvs.h> 


See also: 


nvs_commit 


nvs_set_u16 


Save an unsigned 16 bit integer. 


esp err t nvs set ul6é( 
nvs_handle handle, 
const char *key, 





uintl6 t value) 
Includes: 
¢ #include <nvs.h> 


See also: 


nvs_commit 


nvs_set_u32 


Save an unsigned 32 bit integer. 


esp err t nvs_ set u32 ( 
nvs_handle handle, 
const char *key, 
uint32_ t value) 





Includes: 


¢ #include <nvs.h> 
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See also: 


nvs_commit 


nvs_set_u64 
Save an unsigned 64 bit integer. 


esp err t nvs set u64 ( 





nvs_handle handle, 
const char *key, 
uint64 t value) 


Includes: 
¢ #include <nvs.h> 


See also: 


nvs_commit 


Partition API 
See also: 


Partition table 


esp_partition_erase_range 
Erase a range of data within a partition. 


esp err t esp partition erase range ( 
const esp partition _t* partition, 
uint32_ t start_addr, 
uint32 £ size); 


Includes 


¢ #include <esp_partition.h> 


esp_partition_find 
Find a partition with a given type and optionally a subtype and/or label. 


esp partition iterator t esp partition _find( 
esp partition type t type, 
esp partition subtype t subtype, 
const char* label) 


* type — The type of partition being sought. One of: 
o ESP_PARTITION_TYPE_APP 
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o ESP_PARTITION_TYPE_DATA 
* subtype — The sub type of the partition being sought. One of: 
o ESP_PARTITION_SUBTYPE_APP_FACTORY 
o ESP_PARTITION_SUBTYPE_APP_OTA_xxx 
o ESP_PARTITION_SUBTYPE_APP_TEST 
o ESP_PARTITION_SUBTYPE_DATA_OTA 
o ESP_PARTITION_SUBTYPE_DATA_PHY 
o ESP_PARTITION SUBTYPE_DATA_NVS 
o ESP_PARTITION_SUBTYPE_DATA_ESPHTTPD 
o ESP_PARTITION_SUBTYPE_DATA_FAT 
o ESP_PARTITION_SUBTYPE_DATA_SPIFFS 
o ESP_PARTITION_SUBTYPE_DATA_COREDUMP 
o ESP_PARTITION_SUBTYPE_ANY 
* label — The label of the partition being sought or NULL for don't care. 


The return is an iterator that can be used to iterate over the found partitions. If no 
partitions were found that matched, then NULL is returned. The iterator must be 
released with esp partition iterator release () when finished. To move to the next 
iterator call esp partition next(). 


Includes 
¢ #include <esp_partition.h> 


See also: 


esp_partition_get 
esp_partition_iterator_release 


esp_partition_find_first 
Obtain the first partition that matches the details or NULL if none match. 


const esp partition t* esp partition find first ( 
esp partition type t type, 
esp partition subtype t subtype, 
const char* label) 


* type — The type of partition being sought. One of: 
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o ESP_PARTITION_TYPE_APP 

o ESP_PARTITION_TYPE_DATA 

subtype — The sub type of the partition being sought. One of: 
o ESP_PARTITION_SUBTYPE_APP_FACTORY 

o ESP_PARTITION_SUBTYPE_APP_OTA_xxx 

o ESP_PARTITION_SUBTYPE_APP_TEST 

o ESP_PARTITION_SUBTYPE_DATA_OTA 

o ESP_PARTITION_SUBTYPE_DATA_PHY 

o ESP_PARTITION_SUBTYPE_DATA_NVS 

o ESP_PARTITION_SUBTYPE_DATA_ESPHTTPD 
o ESP_PARTITION_SUBTYPE_DATA_FAT 

°o ESP_PARTITION_SUBTYPE_DATA_SPIFFS 

o ESP_PARTITION_SUBTYPE_DATA_COREDUMP 
o ESP_PARTITION_SUBTYPE_ANY 


label — The label of the partition being sought or NULL for don't care. 


The return is an instance of the description of the partition. That is a data structure that 
contains: 
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type — One of 

o ESP_PARTITION_TYPE_APP 

o ESP_PARTITION_TYPE_DATA 

subtype — One of: 

o ESP_PARTITION_SUBTYPE_APP_FACTORY 
o ESP_PARTITION_SUBTYPE_APP_OTA_xxx 

o ESP_PARTITION_SUBTYPE_APP_TEST 

o ESP_PARTITION_SUBTYPE_DATA_OTA 

o ESP_PARTITION_SUBTYPE_DATA_PHY 

o ESP_PARTITION_SUBTYPE_DATA_NVS 

o ESP_PARTITION_SUBTYPE_DATA_ESPHTTPD 
o ESP_PARTITION_SUBTYPE_DATA_FAT 

o ESP_PARTITION_SUBTYPE_DATA_SPIFFS 


o ESP_PARTITION_SUBTYPE_DATA_COREDUMP 
* address — Starting address of the partition in flash. 
* size — Size of the partition in bytes. 
* label — NULL terminated string describing the partition. 
* encrypted — True if the partition is encrypted. 
Includes 


¢ #include <esp_partition.h> 


esp_partition_get 
Get the partition details for the current iterator. 


const esp partition t* esp partition _get(esp partition iterator t iterator) 


The return is an instance of the description of the partition. That is a data structure that 
contains: 


* type — One of 
o ESP_PARTITION_TYPE_APP 
o ESP_PARTITION_TYPE_DATA 
* subtype — One otf: 
o ESP_PARTITION_SUBTYPE_APP_FACTORY 
o ESP_PARTITION_SUBTYPE_APP_OTA_xxx 
o ESP_PARTITION_SUBTYPE_APP_TEST 
o ESP_PARTITION_SUBTYPE_DATA_OTA 
o ESP_PARTITION_SUBTYPE_DATA_PHY 
o ESP_PARTITION_SUBTYPE_DATA_NVS 
o ESP_PARTITION_SUBTYPE_DATA_ESPHTTPD 
o ESP_PARTITION_SUBTYPE_DATA_FAT 
o ESP_PARTITION_SUBTYPE_DATA_SPIFFS 
o ESP_PARTITION_SUBTYPE_DATA_COREDUMP 
* address — Starting address of the partition in flash. 


* size — Size of the partition in bytes. 
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* label — NULL terminated string describing the partition. 
* encrypted — True if the partition is encrypted. 

Includes 
¢ #include <esp_partition.h> 


See also: 


esp_partition_find 


esp_partition_iterator_release 
Release a previously constructed iterator. 


void esp partition_iterator release(esp partition iterator t iterator) 
Includes 
¢ #include <esp_partition.h> 


See also: 


esp_partition_find 


esp_partition_mmap 
Memory map the partition. 


esp err t esp partition_mmap ( 
const esp partition _t* partition, 
uint32_ t offset, 
uint32_ t size, 
spi flash mmap memory t memory, 





const void** out_ptr, 
spi flash mmap handle t* out handle) 





Includes 


¢ #include <esp_partition.h> 


esp_partition_next 
Move the iterator to the next partition element. 


esp partition iterator _t esp partition _next(esp partition iterator t iterator) 
Includes 
¢ #include <esp_partition.h> 


See also: 


esp_partition_find 
esp_partition_iterator_release 
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esp_partition_read 
Read data from the partition. 


esp err t esp partition_read ( 
const esp partition _t* partition, 
size_t src _ offset, 
void* dst, 
size t size) 


Includes 


¢ #include <esp_partition.h> 


esp_partition_write 
Write data to the partition. 


esp err t esp partition write ( 
const esp partition _t* partition, 
size t dst_offset, 
const void* src, 
size t size) 


Includes 


¢ #include <esp_partition.h> 


Virtual File System 
See also: 


Virtual File System 


esp_vfs_dev_uart_register 
void esp vfs dev uart register () 





Register the virtual file system known as "/dev/uart" as a serial port interface. We can 


thus access "/dev/uart/0", "/dev/uart/1" and "/dev/uart/2". 


Functions support by this file system are: 


° open — 
° close- 
° write- 


* fstat — 
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Note that read() is not yet supported. 


See also: 


Using the VFS component with serial 


esp_vfs_register 
Register a new VFS. 


esp err t esp vfs register ( 





const char *base path, 

const esp vfs _ t *vfs, 

void *ctx); 
Register a new virtual file system. The base_path is a C string that can be no more 
than ESP_VFS_ PATH MAx Characters in length (currently defined as 15). It must start with 
a"/" character and must not end with a"/". This will serve as the junction point for 
accessing data through this file system. 





The vfs is a pointer to an esp vfs + that must be populated by the application making 
the call to esp vfs register. The data structure does not have to be maintained after 
making the call as a copy is made. 


The ctx is a pointer to data that is passed to the registered functions if the vfs "flags" 
attribute is set to ESP VFS FLAG CONTEXT PTR. When used, all the callback functions 
have an additional option which is the context. The names of the functions change to 
have an" p" after them. For example, with the default setting, the close function 
signature is: 








int close(int fd) 


while when the context flag is set, the function signature changes to: 


int close p(void *ctx, int fd) 
and the assignment property in the esp vfs +t structure changes to the " p" versions. 
Within the esp vfs_t data structure we have the following fields: 

* fd offset — Offset value for numeric file descriptors. 


* flags — Flags associated with this VFS. Choices today are: 





© ESP VFS FLAG DEFAULT — Default value. 




















© ESP VFS FLAG CONTEXT PTR— The context pointer functions are used and the 
context data is passed in. 


* write —A function called to write data. 


size t (*write) (int fd, const void *data, size t size) 
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Write into the file specified by the fa file descriptor the data pointed to by data of length 
size bytes. The return is the number of bytes actually written. 


* 1seek —A function called to seek within a file. 


off t (*lseek) (int fd, off _t offset, int whence) 


The whence parameter is the controller of how offset is applied: 





© SEEK SET — Set the position to an absolute of offset. 

















© SEEK CUR — Set the position relative to the current position plus offset. Offset 
can be negative to seek backwards. 














© SEEK END — Set the position relative to the end of the file plus offset. Offset 
can be used as 0 or negative. 








* read —A function called to read data. 


ssize t (*read) (int fd, void *dst, size t size) 


* open —A function called to open a file. 


int (*open) (const char *path, int flags, int accessMode) 


The path is the path to the local file. The VFS prefix is removed and only the local file 
part is passed in. The flags are the operational flags as described in the Unix open () 
system call. The accessMode are the permission of the file when it is created. 


* close —A function called to close a file. 


int (*close) (int fd) 


* fstat —A function called to stat a file by file descriptor. 


int (*fstat) (int fd, struct stat *st) 


* stat —A function called to stat a file by name. 


int (*stat) (const char *path, struct stat *st) 
The struct stat contains: 


° st_dev 
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° st_ino 

° sgt_mode 
© st_nlink 
° st_uid 

° 6st_gid 

° st_rdev 
° st_size 
° st_blksize 
° gt_blocks 
° st_atime 
° st_mtime 


° st_ctime 


* j1ink —A function called to link a file. 


int (*link) (const char *oldPath, const char *newPath) 


The mapped POSIX api is: man(2) — link 


* unlink —A function called to unlink a file. 


int (*unlink) (const char *path) 


The mapped POSIX api is: man(2) — unlink 





* rename —A file called to rename a file. 


int (*rename) (const char *oldPath, const char *newPath) 


* opendir — Open a directory for reading. 


DIR *opendir(const char *name) 


* readdir — Read the next entry in the directory stream. 


struct dirent readdir(DIR *pdir) 
See also: 
man(3) — readdir 


* telldir — Return the current location in the directory stream. 
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long telldir(DIR *pdir) 


See also: 
man(3) — telldir 


* seekdir — Set the position of the next readdir(). 


void seekdir(DIR *pdir, long offset) 
See also: 
man(3) — seekdir 


* closedir — Close a directory. 
int closedir(DIR *pdir) 
See also: 
man(3) — closedir 


* mkdir — Create a directory. 


int mkdir(const char *name, mode_t mode) 





See also: 
man(3) — mkdir 


* rmdir — Delete a directory. 


int rmdir(const char *name) 


See also: 
man(2) — rmdir 
Includes: 
* esp vfs.h 
See also: 
man(2) — open 
man(2) — close 


man(3) — closedir 
man(2) — fstat 
man(2) — link 
man(3) — mkdir 
man(3) — readdir 
man(2) — rename 
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man(2) — rmdir 
man(3) — seekdir 
man(2) — stat 
man(3) — telldir 
man(2) — unlink 
man(2) — write 


FatFs file system 
See also: 


FatFs File System 


esp_vfs_fat_register 

esp err t esp vfs fat register ( 
const char* base path, 
const char* fat_drive, 





size t max files, 
FATFS** out_fs) 


The base _path is where the FATFS should be registered. 


The fat_drive is a FATFS drive specification. If we only have one drive then this can 
be the empty string. 


The max files is the maximum number of files we can have open at one time. 
The out_fs is a pointer to the FATFS structure used in the £ mount () call. 
Includes: 


¢ #include <esp_vfs_fat.h> 


esp_vfs_fat_sdmmc_mount 
Mount an SD card as a posix file system. 


esp err t esp vfs fat sdmmc mount ( 
const char *base path, 
const sdmmc_host_t *host_ config, 
const sdmmc_slot_config t *slot_config, 





const esp vfs_ fat _sdmmc_mount_config t *mount_config, 
sdmmc_card_t **out_card) 





The base path is the path in the POSIX file system which acts as the mount point for 
the files hosted in the FAT32 file system contained on the card. Acommon example is 


"/sdcard’. 


The host_config is an instance of sdmmc_host_t and is commonly configured using 
SDMMC_HOST DEFAULT(). For example: 





sdmmc_host_t host config = SDMMC_ HOST DEFAULT (); 
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The sdmmc_ host _t is aC structure that contains: 





* uint32 t flags — Define operational flags. These include: 
© SDMMC_HOST FLAG 1B1T — Host uses 1-line SD protocol. 


© SDMMC_HOST FLAG 4BIT — Host uses 4-line SD protocol. 





© SDMMC_HOST FLAG 8BIT — Host uses 8-line SD protocol. 





























© SDMMC_HOST FLAG spi — Host uses SPI protocol. 
* int slot — Unknown 
°* int max freq khz— Unknown 
* float io voltage — Unknown 
* init — Function to be called to initialize the host layer. 
* set bus width — Function to be called to set the bus width. 
* set _card_clk — Function to be called to set the clock. 
* do transaction — Function to be called to perform a transaction. 


* deinit — Function to be called to de-initialize the host layer. 



































Using the spwmc_HosT DEFAULT () to initialize the structure sets the following default 
values: 

Property Value 

flags SDMMC_HOST_ FLAG 4BIT 
slot SDMMC_HOST_SLOT_1 
max_freq_khz SDMMC_ FREQ DEFAULT 
io_voltage 3.3 

init sdmmc_host_init 

set_bus_ width sdmmc_host_set_bus_ width 
set_card_ clk sdmmc_host_set_card_clk 
do_transaction sdmmc_host_do_transaction 
deinit sdmmc_host_deinit 














The slot _config parameter is an instance of sdmmc_slot_config_t and is commonly 
configured using spMMc_SLOT CONFIG DEFAULT (). 





The mount_ config parameter is an instance of esp vfs far sdmmc mount config t 
which has properties: 
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* format_if_mount_failed 
* max_files 
Includes: 
¢ #include <esp_vfs_fat.h> 


See also: 


esp_vfs_fat_sdmmc_unmount 


esp_vfs_fat_sdmmc_unmount 
esp err t esp vfs fat sdmmc unmount () 





Includes: 
¢ #include <esp_vfs_fat.h> 


See also: 


esp_vfs_fat_sdmmc_mount 


esp_vfs_fat_unregister 
esp err t esp vfs fat unregister() 





Includes: 


¢ #include <esp_vfs_fat.h> 


f_mount 
FRESULT £ mount (FATFS *fs, const char *path, BYTE opt) 








The values of opt can be: 
¢ 0-— Don't mount now. 
¢ 1 —Mount now and check it is ready for work. 


See also: 


FatFs manual —f mount 





ff_diskio_register 
void ff diskio register ( 
BYTE pdrv, 
const ff diskio_impl_t *diskio_impl) 
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SPI Flash 


The SPI Flash apis allow us to read, write and erase sectors contained within flash 
memory. When working with flash address spaces, we need to ensure that we tell the 
ESP-IDF configuration how much flash space is available. We do that in the "make 
menuconfig" options. The default is 2MBytes. Attempts to access above 2MBytes will 


be flagged as an error, even if your real storage exceeds that. 





Terminal File Edit View Search Terminal Help 


Serial flasher config 
Arrow keys navigate the menu. <Enter> selects submenus ---> (or empty submenus 
----). Highlighted letters are hotkeys. Pressing <Y> includes, <N> excludes, 
<M> modularizes features. Press <Esc><Esc> to exit, <?> for Help, </> for 
Search. Legend: [*] built-in [ ] excluded <M> module < > module capable 


(/dev/ttyUSBO) Default serial port 

Default baud rate (115200 baud) ---> 
[ ] Use compressed upload 

Flash SPI mode (DIO) ---> 

Flash SPI speed (40 MHz) —_— 
a 


[*] Detect flash size when flashing bootloader (NEW) 


Before flashing (Reset to bootloader) ---> 
After flashing (Reset after flashing) ---> 
‘make monitor' baud rate (115200 bps) ---> 























spi_flash_erase_range 
Erase a range of flash storage. 





esp err t spi _flash_erase range(size t startAddr, size t size) 





Includes: 


¢ #include <esp_spi_flash.h> 


spi_flash_erase_sector 
Erase a flash sector. Each sector is 4k in size. 


esp err t spi _flash_erase sector(size t sector) 





The sec parameter is the sector number (a sector is 4096 bytes in size). 


Includes: 
¢ #include <esp_spi_flash.h> 


See also: 
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spi_flash_get_chip_size 
Get the size of the declared storage for the flash device. 


size t spi flash get chip size() 





The return is the amount of storage that the environment has declared to be available 
on the flash device. 


Includes: 


¢ #include <esp_spi_flash.h> 


spi_flash_get_counters 
const spi_flash_counters t *spi_flash_get counters () 





Includes: 


¢ #include <esp_spi_flash.h> 


spi_flash_init 


void spi_flash_init() 
Includes: 


¢ #include <esp_spi_flash.h> 


spi_flash_mmap 

esp err t spi flash mmap( 
uint32 t srcAddr, 
size t size, 





spi flash mmap memory t memory, 





const void **outPtr, 
spi flash mmap handle t *outHandle) 





The srcAddr is the address in flash address range that is the start of the data we are 
going to map from. It must be located on a 64K boundary (i.e. be evenly divisible by 
64*1024 which is 0x1 0000). 


The size is the size of data to be mapped. It will be rounded up to the nearest 64K 
multiple. 


The memory is where the memory should be mapped. Choices are: 


* SPI FLASH MMAP DATA — Map to data memory. 








* SPI FLASH MMAP Inst — Map to instruction memory. 





The outPtr is the address in the CPU address range where the mapped data can be 
found. 
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The outHandle is the handle used to release the mapping (if needed) in a call to 


spi_flash_munmap. 
Includes: 
¢ #include <esp_spi_flash.h> 


See also: 


spi_flash_munmap 
spi_flash_mmap_dump 
esp_partition_mmap 


spi_flash_mmap_dump 
void spi_flash_mmap_dump() 


Includes: 


¢ #include <esp_spi_flash.h> 


spi_flash_munmap 
void spi_flash_munmap(spi flash_mmap_ handle t handle) 





Includes: 


¢ #include <esp_spi_flash.h> 


spi_flash_read 
Read data from flash 


esp_err t spi_flash_read(size _t src_addr, void *destAddr, size t size) 





The src_addr parameter is the address in flash that will be read. The destAddr is the 
address in memory which will be written. The size parameter is the size of data to be 
read. 


Includes: 
¢ #include <spi_flash.h> 


See also: 


spi_flash_reset_counters 
void spi_flash_reset counters () 
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spi_flash_write 
Write data to flash 


esp err t spi_flash _write(size t destAddr, const void *srcAddr, size t_t size) 





The destAddr is the address in flash which is to be written. The srcAddr is the source 
address in memory from where the new data is to be taken. The size parameter is the 
size of the data to be written. 


Includes: 
¢ #include <spi_flash.h> 


See also: 


SDMMC 


sdmmc_card_init 

esp err t sdmmc_card_ init ( 
const sdmmc_host_t *host, 
sdmmc_card_t* out_card) 


Includes: 


¢ #include <sdmmc_cmd.h> 


sdmmc_card_print_info 
void sdmmc_card_print_info( 
FILE *stream, 
const sdmmc_card_t *card) 





Includes: 


¢ #include <sdmmc_cmd.h> 


sdmmc_host_deinit 
esp err t sdmmc_host_deinit() 


Includes: 


¢ #include <sdmmc_host.h> 


sdmmc_host_do_transaction 

esp err t sdmmc_host_do_ transaction ( 
int slot, 
sdmmc_command_t *cmdinfo) 


Page 670 


Includes: 


¢ #include <sdmmc_host.h> 


sdmmc_host_init 
esp_err t sdmmc_host_init() 


Includes: 


¢ #include <sdmmc_host.h> 


sdmmc_host_init_slot 
esp_err t sdmmc_host_init_slot( 
int slot, 
const sdmmc_slot_config t *slot_config) 


Includes: 


¢ #include <sdmmc_host.h> 


sdmmc_host_set_bus_width 
esp err t sdmmc_host_set_bus_ width ( 





int slot, 
size_t width) 


Includes: 


¢ #include <sdmmc_host.h> 


sdmmc_host_set_card_clk 
esp_err_ t sdmmc_host_set_card_clk( 
int slot, 
uint32 t freq_khz) 





Includes: 


¢ #include <sdmmc_host.h> 


sdmmc_read_sectors 
esp_err t sdmmc_read_sectors ( 
sdmmc_card_t *card, 
void *dst, 
size t start _sector, 
size_t sector count) 
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Includes: 


¢ #include <sdmmc_cmd.h> 


sdmmc_write_sectors 
esp err t sdmmc_write sectors ( 
sdmmc_card_t *card, 
const void* src, 
size t start _sector, 
size_t sector count) 


Includes: 


¢ #include <sdmmc_cmd.h> 
Hardware Timers 


timer_disable_intr 

esp_err t timer disable intr ( 
timer group_t group_num, 
timer idx t timer num) 


* group _num— One of: 


O° TIMER GROUP_0 








© TIMER _GROUP_ 1 


* timer num— One of: 








ie) TIMER 0 
ie) TIMER 1 
Includes: 


¢ #include <driver/timer.h> 


timer_enable_intr 

esp_err t timer enable intr ( 
timer group_t group_num, 
timer idx t timer num) 


* group _num— One of: 


O° TIMER GROUP 0 








© TIMER _GROUP_1 


* timer num— One of: 
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a) 

j 
H 
S 
GI 
cs) 
je) 








° 
=| 
H 
= 
Gl 
vs) 


Includes: 


¢ #include <driver/timer.h> 


timer_get_alarm_value 


Get the value at which a timer event should fire. 


esp_err t timer _get_alarm value ( 
timer group_t group_num, 
timer idx t timer num, 
uint64 t *alarm value) 


* group _num— One of: 


O° TIMER GROUP_0 











O° TIMER GROUP 1 


* timer num— One of: 








ie) TIMER 0 
° TIMER 1 
Includes: 


¢ #include <driver/timer.h> 


timer_get_config 

esp_err t timer _get_config( 
timer group_t group_num, 
timer idx t timer num, 
timer config t *config) 


* group _num— One of: 


O° TIMER GROUP_0 








© TIMER _GROUP 1 


* timer num— One of: 


(©) 
FH 
H 
s 
ea 


ER 0 





12) 
HH 
H 
K 
a 


ER 1 





* config — Contains 
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° alarm_en 

© counter_en 

© counter_dir 

° intr_type 

°o auto_reload 

© divider 
Includes: 


¢ #include <driver/timer.h> 


timer_get_counter_time_sec 
Read the counter value as a double in seconds. 


esp err t timer get counter time_sec( 
timer group_t group_num, 
timer idx t timer num, 
double *time) 


* group _num— One of: 


O° TIMER GROUP_0 








© TIMER _GROUP_ 1 


* timer num— One of: 


O° TIMER 0 








ie) TIMER 1 
Includes: 


¢ #include <driver/timer.h> 


timer_get_counter_value 
Get the value of the timer. 


esp err t timer get counter value ( 
timer group_t group_num, 
timer idx t timer num, 
uint64 t *timer val) 


* group _num— One of: 


© TIMER GROUP_0 
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© TIMER _GROUP_1 





* timer num— One of: 








ie) TIMER 0 
ie) TIMER 1 
Includes: 


¢ #include <driver/timer.h> 


timer_group_intr_enable 

esp err t timer group _intr_enable( 
timer group_t group_num, 
uint32_t en_mask) 


* group _num— One ot: 


O° TIMER GROUP_0 








© TIMER _GROUP_1 
Includes: 


¢ #include <driver/timer.h> 


timer_group_intr_disable 

esp err t timer group _intr_ disable ( 
timer group_t group_num, 
uint32 t disable mask) 


* group _num— One ot: 


O° TIMER GROUP_0 








© TIMER _GROUP_1 
Includes: 


¢ #include <driver/timer.h> 


timer_isr_register 

esp err t timer _isr register ( 
timer group_t group_num, 
timer idx t timer num, 
void (*fn) (void*), void * arg 
int intr_alloc_ flags, 
timer isr handle t *handle) 
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* group _num— One of: 


© TIMER GROUP_0 








© TIMER GROUP 1 


* timer num— One of: 


O° TIMER_O 








ie) TIMER 1 
Includes: 


¢ #include <driver/timer.h> 


timer_init 

esp_err t timer init ( 
timer group_t group_num, 
timer idx t timer num, 
timer config t* config) 


* group _num— One of: 


© TIMER GROUP_0 








© TIMER GROUP 1 


* timer num— One of: 


O° TIMER_O 





O TIMER 1 





* config — Contains 


° alarm_en 


(0) 


counter_en 


(0) 


counter_dir 


oO 


intr_type 


O 


auto_reload 


(0) 


divider 
Includes: 


¢ #include <driver/timer.h> 


timer_pause 
Pause a specific timer. 
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esp err t timer pause ( 
timer group_t group_num, 
timer idx t timer num) 


* group _num— One of: 


O° TIMER GROUP_0 








© TIMER _GROUP_1 


* timer num— One of: 


Oo TIMI 


Gl 


R_O 








Oo TIMI 


Gl 


R 1 


timer_set_counter_value 
Set the counter value to a specific value., 


esp err t timer set counter value ( 
timer group_t group_num, 
timer idx t timer num, 
uint64 t load_val) 


* group _num— One of: 


O° TIMER GROUP_0 








© TIMER _GROUP_1 


* timer num— One of: 








ie) TIMER 0 
ie) TIMER 1 
Includes: 


¢ #include <driver/timer.h> 


timer_start 
Start a specific timer. 


esp err t timer start ( 
timer group_t group_num, 
timer idx t timer num) 


* group _num— One of: 


O° TIMER GROUP_0 








© TIMER _GROUP_1 
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* timer num— One of: 


O° TIMER_O 








ie) TIMER _ 1 
Includes: 


¢ #include <driver/timer.h> 


timer_set_alarm 
Determine if an alarm should fire. 


esp_err t timer _set_alarm( 
timer group_t group_num, 
timer idx t timer num, 
timer alarm_t alarm _en) 


* group _num— One of: 


© TIMER GROUP_0 








© TIMER GROUP 1 


* timer num— One of: 


O° TIMER 0 





O° TIMER 1 





* alarm en—One of: 
° TIMER_ALARM_DIS 
° TIMER_ALARM_EN 
Includes: 


¢ #include <driver/timer.h> 


timer_set_alarm_value 
Define the value at which an alarm event should occur when reached by the timer. 


esp err t timer _set_alarm value ( 
timer group_t group_num, 
timer idx t timer num, 
uint64 t alarm value) 


* group _num— One of: 


° TIMER GROUP_0 








© TIMER GROUP 1 
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* timer num— One of: 


O° TIMER 0 








ie) TIMER _ 1 
Includes: 


¢ #include <driver/timer.h> 


timer_set_auto_reload 
Determine whether or not the timer should reload following an alarm event. 


esp err t timer set _auto_ reload ( 
timer group_t group_num, 
timer idx t timer num, 
timer autoreload_t reload) 


* group _num— One of: 


© TIMER GROUP_0 








© TIMER _GROUP_1 


* timer num— One of: 


O° TIMER 0 








O TIMER 1 


* reload — One of: 





© TIMER AUTORELOAD Dis — Do not load the counter after an alarm event. 























© TIMER AUTORELOAD EN — Load the counter after an alarm event. 





Includes: 


¢ #include <driver/timer.h> 


timer_set_counter_mode 
Set the mode of a specific counter. 


esp err t timer set counter mode ( 
timer group_t group_num, 
timer idx t timer num, 
timer count dir _t counter dir) 


* group _num— One of: 
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© TIMER GROUP_0 








© TIMER GROUP 1 


* timer num— One of: 


O° TIMER_O 








Oo TIMER 1 

* counter dir — One of: 
° TIMER_COUNT_DOWN 
o TIMER_COUNT_UP 


Includes: 


¢ #include <driver/timer.h> 


timer_set_divider 
Set the underlying clock divider. 


esp_err t timer set divider ( 
timer group_t group_num, 
timer idx t timer num, 
uintl6 t divider) 


* group _num— One of: 


© TIMER GROUP_0 








© TIMER GROUP 1 


* timer num— One of: 


O° TIMER_O 








ie) TIMER 1 
Includes: 


¢ #include <driver/timer.h> 


Watchdog processing 

The watchdog functions are all about monitoring liveness of tasks to ensure that they 
aren't stuck in loops or otherwise starving. The watchdog functions are controlled by 
the master settings defined by running "make menuconfig". There are entries in there 
which define whether or not task specific watchdog functions are enabled and, if so, 
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how long between watchdog checks. The interval is measured in seconds with a 
default of 5. The duration is measured in seconds which feels like an exceptionally long 
time in processing units. 


If a Watchdog timer expires before being fed, then a message is logged (by default). 
Alternatively, we can invoke a panic handler which can: 


¢ print the registers and halt 
* print the registers and reboot 
¢ silently reboot 


¢ invoke the built-in gdb stub 


esp_int_wdt_init 
Initialize the interrupt watchdog. 


void esp int _wdt_init() 


esp_task_wdt_init 
Initialize the task watchdog. 


void esp_task wdt_init() 


esp_task_wdt_feed 
Register a task or feed a task watchdog. 


void esp_task wdt_feed() 
If called for the first time on a given FreeRTOS task then the task becomes registered 


as one that is being monitored for liveness. It must be regularly called from then on to 
ensure that the watchdog is fed. 


esp_task_wdt_delete 
Delete an association between a task and watchdog. 


void esp _task_wdt_delete() 
If in the past, the current task has called esp task wdt feed() then it is considered on 
the watch list. If the task no longer wishes to watched for liveness or else is about to 


end, then we should call this function to remove the task from the list of monitored tasks 
by the watchdog. 
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JSON processing 
The ESP-IDF provides a C implementation of JSON processing through the component 
called "json". 


Note: There is a second JSON parsing option called "jsmn" which uses an alternate 
technique that exchanges minimalism for efficiency. 


We can parse a JSON string using cJson _Parse(). This will return a czson data 


structure. 


° ova 


° va 


° ova 


This data structure exposes: 


lueint — The number value as an integer. 


luedouble — The number value as a double. 





luestring — The string value. 


To serialize a JSON object to a string representation we can call cJSon Print (). 


The complete list of functions are: 
¢ cJSON Parse 
¢ cJSON_Print 
¢ cJSON_PrintUnformatted 
¢ cJSON_PrintBuffered 
¢ cJSON _PrintPreallocated 
* cJSON_Delete 
¢ cJSON_GetArraySize 
¢ cJSON_GetArrayltem 
* cJSON_GetObjectltem 
¢ cJSON_GetErrorPtr 
¢ cJSON_ CreateNull 
¢ cJSON_ CreateTrue 
¢ cJSON_ CreateFalse 
¢ cJSON_ CreateNumber 
* cJSON_CreateString 
¢ cJSON_CreateArray 
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cJSON_CreateObject 
cJSON_CreatelntArray 
cJSON_CreateFloatArray 
cJSON_CreateDoubleArray 
cJSON_CreateStringArray 
cJSON_AddltemToArray 
cJSON_AddltemToObject 
cJSON_AddltemToObjectCS 
cJSON_AddltemReference ToArray 
cJSON_AddltemReference ToObject 
cJSON_DetachltemFromArray 
cJSON_DeleteltemFromArray 
cJSON_DetachltemFromObject 
cJSON_DeleteltemFromObject 
cJSON_InsertltemInArray 
cJSON_ReplaceltemInArray 
cJSON_ReplaceltemInObject 
cJSON_Duplicate 
cJSON_Minify 
cJSON_AddNullToObject 
cJSON_AddTrueToObject 
cJSON_AddFalseToObject 
cJSON_AddBoolToObject 
cJSON_AddNumberToObject 
cJSON_AddString ToObject 
cJSON_ArrayForEach 
cJSON_SetIntValue 
cJSON_SetNumberValue 
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Includes: 
¢ #include <cJSON.h> 


See also: 


Github: DaveGamble/cJSON 
JSMN 





HTTP/2 processing 
The ESP-IDF provides an implementation of HTTP/2 parsing through "nghttp2". 


See also: 


HTTP/2 C library and tools — nghttp2.org 





Parsing XML - expat 
The ESP-IDF provides a version of expat which is an XML parsing library. 


See also: 


Expat home page 
Using Expat 
Expat reference document 





Arduino - ESP32 HAL for UART 


uartAvailable 
uint32 t uartAvailable(uart_t *uart) 


Includes: 


¢ #include <esp32-hal-uart.h> 


uartBegin 
Initialize a UART for work. 


uart_t *uartBegin ( 
uint8 t uartNumber, 
uint32 t baudrate, 
uint32_ t config, 
int8 t rxPin, 
int8 t txPin, 
uint16 t queueLen, 
bool inverted) 
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The uartNumber can be one of the three UARTs on the device. They are numbered 0, 1 
and 2. The rxpPin is the pin used for receiving incoming data, The txpPin is the pin used 
to transmit data. If -1 is specified, then the UART is input or output only. It is invalid to 
specify -1 for both pins (i.e. a uart with neither input nor output). The config parameter 
is the configuration for the UART. Aconfiguration is broken into three parameters: 


¢ Number of bits — 5,6,7 or 8 
e Parity checking — None, Even or Odd 
¢ Number of stop bits — 1 or 2 


Constants are defined for all possibilities in the form: 


SERIAL <NUMBER OF BITS><PARITY><NUMBER OF STOP BITS> 














For example: 


SERIAL 8N1 





Means 8 bits, no parity check, 1 stop bit. 
Includes: 
* esp32-hal-uart.h 


See also: 


uartEnd 


uartEnd 
Release resources associated with the uart. 





void uartEnd(uart_t *uart) 
Includes: 
* esp32-hal-uart.h 


See also: 


uartBegin 


uartFlush 
void uartFlush(uart_t *uart) 


Includes: 


* esp32-hal-uart.h 
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uartGetBaudRate 
Get the current baud rate of the uart. 


uint32 t uartGetBaudRate(uart_t *uart) 
Includes: 
* esp32-hal-uart.h 


See also: 


uartSetBaudRate 
uartBegin 


uartGetDebug 


int uartGetDebug() 
Includes: 
* esp32-hal-uart.h 


See also: 


uartSetDebug 


uartPeek 
Retrieve the next byte to be read without actually consuming it. 


uint8 t uartPeek(uart_t *uart) 
Includes: 
* esp32-hal-uart.h 


See also: 


uartRead 


uartRead 
Read a byte from the uart. 


uint8 t uartRead(uart_t *uart) 
Includes: 
* esp32-hal-uart.h 


See also: 


uartAvailable 
uartPeek 
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uartSetBaudRate 
Set the baud rate of the uart. 
void uartSetBaudRate(uart_t *uart, uint32_ t baud_rate) 
Includes: 
* esp32-hal-uart.h 


uartGetBaudRate 
uartBegin 


uartSetDebug 
Specify a uart as the target of debug data. 


void uartSetDebug(uart_t *uart) 
Includes: 
* esp32-hal-uart.h 


See also: 


uartGetDebug 


uartWrite 
Write a single byte to the uart. 


void uartWrite(uart_t *uart, uint8 t c) 
This is a blocking call and waits for the transmission to complete. 
Includes: 


* esp32-hal-uart.h 


uartWriteBuf 
Write a buffer of bytes to the uart. 


void uartWriteBuf ( 

uart_t *uart, 

const uint8 t *data, 

size t len) 
Writes the buffer to the uart blocking until completion. 
Includes: 


* esp32-hal-uart.h 


Page 687 


Arduino - ESP32 HAL for I2C 
See also: 


Using Arduino |2C libraries 


i2cAttachSCL 
Associate the bus's clock signal with a specific GPIO pin. 


i2c_err t 1i2cAttachSCL(i2c_t *i2c, int8 t scl) 


i2cAttachSDA 


i2c_err t i2cAttachSDA(i2c_t *i2c, int8 t sda) 


Associate the bus's data signal with a specific GPIO pin. 


i2cDetachSCL 


i2c_err t 12cDetachSCL(i2c_t *i2c, int8 t scl) 


Disassociate the bus's clock signal with a specific GPIO pin. 


i2cDetachSDA 


i2c_err_ t 12cDetachSDA(i2c_t *i2c, int8 t sda) 


Disassociate the bus's data signal with a specific GPIO pin. 


i2cGetFrequency 
uint32 t i2cGetFrequency(i2c_ t *12c) 


i2clnit 
Initialize access to the I2C bus. 
i2c_t *i2cInit ( 

uint8 t i2c_num, 

uintl6 t slave addr, 

bool addr_10bit_en) 
The i2c_num Is the identify of the 12C bus we are planning on using. The slave addr IS 
the address of the slave device we wish to appear as. The addr _10bit_en would be set 
to true if we are using 10 bit slave addressing. 


The return from this call is a handle that is passed into other calls to refer to this 
bus/device. 
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See also: 


Using Arduino |2C libraries 


i2cRead 
Read data from the I2C bus. 


i2c_err t i2cRead ( 

i2c_t *i2c, 

uint16 t address, 

bool addr _10bit, 

uint8 t *data, 

uint8 t len, 

bool sendStop) 
The i2c is a handle to an I2C bus. The address is the address of the device with which 
we are communicating. The addr_10bit is Set to true if we are using 10 bit addressing. 
The data is a pointer to a buffer to be filled in by the read. The ien is the number of 
bytes to read. The sendStop is a flag which indicates whether we should send a stop 


indication. 


i2cSetFrequency 
i2c_err t 12cSetFrequency(i2c_ t *1i2c, uint32 t clk_speed) 


i2cWrite 
Write data down the I2C bus. 
i2c_err t 12cWrite ( 

i2c_t *i2c, 

uint16 t address, 

bool addr_10bit, 

uint8 t *data, 

uint8 t len, 

bool sendStop) 
The i2c is a handle to an I2C bus. The address is the address of the device with which 
we are communicating. The addr_10bit is Set to true if we are using 10 bit addressing. 
The data is a pointer to a buffer of data to be transmitted. The ien is the size of the 
data to transmit. The sendstop should be true if we are sending a stop flag at the end of 


the transmission. 
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Arduino - ESP32 HAL for SPI 
See also: 


The Arduino Hardware Abstraction Layer SPI 


spiAttachMISO 
Specify the pin to use for MISO. 


void spiAttachMISO(spi_t *spi, int8 t miso) 


spiAttachMOSI 
Specify the pin to use for MOSI. 


void spiAttachMOSI(spi_t *spi, int8 t mosi) 


spiAttachSCK 
Specify the pin to use for SCK. 


void spiAttachSCK(spi_t *spi, int8_t sck) 


spiAttachSS 
Specify the pin to use for SS. 


void spiAttachSS(spi_t *spi, uint8 t cs_num, int8 t ss) 


spiClockDivToFrequency 
Convert a clock divider to a frequency. 


uint32 t spiClockDivToFrequency(uint32 t clockDiv) 


A given clock divider value results in an SPI clock frequency. This function takes a clock 
divider and returns the frequency that would result from using the divider. 


spiDetachMISO 


void spiDetachMISO(spi_t *spi, int8 t miso) 


spiDetachMOSI 


void spiDetachMOSI(spi_t *spi, int8 t mosi) 
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spiDetachSCK 


void spiDetachSCK(spi_t *spi, int8 t sck) 


spiDetachSS 
Detach the pin from SS. 


void spiDetachSS(spi_t *spi, int8 t ss) 


spiDisableSSPins 


void spiDisableSSPins(spi_t *spi, uint8 t cs_mask) 


spiEnableSSPins 


void spiEnableSSPins(spi_t *spi, uint8 t cs_mask) 





spiFrequencyToClockDiv 
Calculate a clock divider needed for a given frequency. 


uint32 t spiFrequencyToClockDiv(uint32 t freq) 


Internally, the SPI clock is based on a given clock divider. Commonly, we want to think 
about SPI clock frequencies. This function calculates the divider necessary to achieve 
a specific frequency. 


spiGetBitOrder 
Retrieve the current bit order. 


uint8 t spiGetBitOrder(spi_t *spi) 
Retrieve the current bit order being used. It will be one of: 
¢ SPI_LSBFIRST 
¢ SPI_MSBFIRST 


spiGetClockDiv 
Get the underlying clock divider. 


uint32 t spiGetClockDiv(spi_t *spi) 


For a given SPI device, get the clock divider. Note that this is not the same as the SPI 
clock frequency. 
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spiGetDataMode 
Retrieve the current data mode. 


uint8 t spiGetDataMode(spi_t *spi) 


Retrieve the current data mode of SPI. It should be one of: 
¢ SPIl_MODEO 


* SPI_MODE1 

* SPI_MODE2 

¢ SPI_MODE3 
spiRead 


Read a buffer of data through SPI. 


void spiRead(spi_t *spi, uint32 t *out, uint8 t len) 


spiReadByte 
Read a single byte of data through SPI. 


uint8 t spiReadByte(spi t *spi) 


spiReadLong 
Read a 32 bit value (a long) from SPI. 


uint32 t spiReadLong(spi_t *spi) 


spiReadWord 
Read a 16 bit value (a word) from SPI. 


uintl6 t spiReadWord(spi_t *spi) 


spiSetBitOrder 
Set the bit order. 


void spiSetBitOrder(spi_t *spi, uint8 t bitOrder) 
The bitorder should be the bit order to be used. It should be one of: 
¢ SPI_LSBFIRST 
¢* SPIMSBFIRST 
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spiSetClockDiv 
Set the clock based on a clock divisor. 


void spiSetClockDiv(spi_t *spi, uint32_t clockDiv) 


spiSetDataMode 
Set the data mode. 


void spiSetDataMode(spi_t *spi, uint8 t dataMode) 


The dataMode is the data mode of SPI. It should be one of: 


¢ SPI_MODEO 
* SPI_MODE1 
* SPI_MODE2 
* SPI_MODE3 
spiSSClear 


void spiSSClear(spi_t *spi) 


spiSSDisable 


void spiSSDisable(spi_t *spi) 


spiSSEnable 


void spiSSEnable(spi_t *spi) 





spiSSSet 


void spiSSSet(spi_t *spi) 


spiStartBus 
Initialize an instance of the bus. 


spi_t *spiStartBus ( 
uint8 t spi_num, 
uint32 t freq, 
uint8 t dataMode, 
uint8 t bitOrder) 
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Initialize an instance of one of the three buses specifying how it should be driven. The 
spi_num is the identity of one of the three buses. It may be one of: 


- FSPI 
> HSPI 
- VSPI 


Note that FSPI is believe to be off-limits for application usage. 


The freq is the speed of the bus. For example 1000000 for 1MHz. The dataMode is the 
data mode of SPI. It should be one of: 


¢* SPI_MODEO 
¢ SPI_MODE1 
¢ SPI_MODE2 
¢ SPI_MODE3 


The bitorder should be the bit order to be used. It should be one of: 
¢ SPI_LSBFIRST 
¢ SPIMSBFIRST 

The return is a reference to an SPI instance. 


See also: 


spiStopBus 


spiStopBus 

Release the resources for an SPI bus. 

void spiStopBus(spi_t *spi) 

The spi is a handle to a bus previously created with a call to spiStartBus(). 
See also: 


spiStartBus 


spiTransferBits 
Transfer bits over SPI and optionally receive response bits. 
void spiTransferBits ( 

spi_t *spi, 

uint32 t sendData, 
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uint32 t *receiveData, 

uint8 t bits) 
The bits is the number of bits to send. Amaximum of 32 bits at one shot. The 
sendData Is the data to send, the receiveData is a pointer to storage to hold retrieved 
data. It may be NULL to indicate that we don't want to receive data. The spi is the 
handle of the SPI interface. 


See also: 


spiStartBus 


spilransferBytes 
Write and read data through SPI. 


void spiTransferBytes ( 

spi_t *spi, 

uint8 t *sendData, 

uint8 t *receiveData, 

uint32_ t size) 
This is the key function in SPI. Here we specify a buffer of data to send through SPI 
and a buffer of data to read from SPI. If we don't need to send data we can specify 
NULL for the sendData and if we don't need to receive, we can specify NULL for 


receiveData. The size is the number of bytes that we are to send and receive. 


spiWaitReady 


void spiWaitReady(spi_t *spi) 


spiWrite 
Write a buffer of data out through SPI. 


void spiWrite(spi_t *spi, uint32_t *data, uint8 t len) 


spiWriteByte 
Write a single byte of data out through SPI. 


void spiWriteByte(spi_t *spi, uint8 t data) 


spiWriteLong 
Write a 32 bit value (a long) out through SPI. 


void spiWriteLong(spi_t *spi, uint32 t data) 
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spiWriteWord 
Write a 16 bit value (a word) out through SPI. 


void spiWriteWord(spi_t *spi, uint1l6 t data) 


Newlib 

When we think of the C programming language we must realize that is exactly what it is 
... a programming language. Functions like "printf" and "strcpy" and "malloc" are not 
part of the C language. They are functions commonly provided by the environment in 
which the compiled program executes. These functions are so prevalent that we 
assume them just to be there when C programming but the reality is that something has 
to provide them. On a Unix/Linux environment, it is the kernel and support user level 
libraries. But what of our ESP32? The answer is an open source library called "newlib". 
Newlib takes the common specifications for many of the functions that we expect to be 
there on a C platform and provides an open source implementation of them. Within the 
ESP32 environment a version of newlib is provided that has been mapped for the 
ESP32. 


From the newlib library, the following functions are exported (and others): 


See also: 


newlib 


abort 
Results in the abnormal termination of the environment (a halt). 


void abort () 


See also: 
man(3) — abort 
abs 


Compute the absolute (non-negative) value of an integer. 


int abs(int val) 
Includes: 
¢  stdlib.h 


See also: 
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man(3) — abs 


asctime 
Format a struct tm time value into a text string. 


char *asctime(const struct tm *tm) 
char *asctime_r(const struct tm *tm, char *buf) 


The struct tm contains: 
¢ tm_sec —0-59 
* tm_min— 0-59 
¢ tm_hour — 0-23 
* tm_mday — 1-31 
* tm_mon — 0-11 
¢ tm_year — Years since 1900 (eg. 2017 = 117) 
* tm_wday — 0-6 
* tm_yday — 0-365 
* tm_isdst — 1/0 
The output format is the same as ctime(). 


See also: 


Timers and time 


man(3) — asctime 


atoi 
Convert a string to an integer. 


int atoi(const char *s) 


See also: 
man(3) — atoi 
atol 


Convert a string to an integer. 


long atol(const char *s) 
See also: 
man(3) — atol 
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bzero 
Zero an area of memory. 


void bzero(void *s, size t n) 
See also: 
man(3) — bzero 


calloc 
Allocate an area of storage for a number of fixed size entries. 


void *calloc(size t c, size t n) 
See also: 


free 
malloc 
realloc 


man(3) — calloc 


check_pos 


close 
Close a file descriptor. 


int close(int fd) 
See also: 
man(3) — close 


creat 
Create a new file. 


int create(const char *path, mode_t mode) 
Includes: 
¢  fentl.h 
See also: 
man(3) — creat 


ctime 
Convert time_t data to a string. 
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char *ctime(const time_t *timep) 


char *ctime r(const ctime_t *timep, char *buf) 


The time _t can be obtained from a call to time (). An example of output would be: 


Thu Jan 1 00:00:00 1970\n 


The length of the string is a constant 25 characters (including the newline). This means 


we can efficiently terminate the line before the newline or just print the first 24 
characters if we don't want to print the newline. 


Note that a newline is found on the end. 
Includes: 
* time.h 


See also: 


Timers and time 
time 


man(3) — ctime 


div 
Compute quotient and remainder. 
div_t div(int numerator, int denominator) 
Includes: 
¢ stdlib.h 
See also: 
man(3) — div 


environ 
Access environment variables. 


char **environ 
Includes: 
* unistd.h 
See also: 
man(3) — environ 


fclose 
Close a stream. 
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int fclose(FILE *fp) 





Includes: 
¢ #include <stdio.h> 
See also: 
man(3) — fclose 


fflush 
Flush a stream. 


int fflush(FILE *fp) 





Includes: 
¢ #include <stdio.h> 
See also: 
man(3) — fflush 


fmemopen 
Perform stream I/O on a buffer of memory. 





FILE *fmemopen(void *buf, size t size, const char *mode) 


The return is a FILE pointer that can be used with other stream I/O functions. The 
mode is the same as found for fopen(). 


Includes: 
¢ #include <stdio.h> 


See also: 


man(3) — fmemopen 





fprintf 
Print to a stream. 


int printf(const char *format, ...) 


Includes: 
¢ #include <stdio.h> 


See also: 


printf 
man(3) — forintf 
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fread 
Read from the file into a memory area. 


size t fread(void *ptr, size t size, size_t nmemb, FIL!I 


Includes: 
¢ #include <stdio.h> 
See also: 
man(3) — fread 


free 
Free allocated memory. 


void free(void *p) 





KE *stream) 


Releases memory previously allocated by a call to malloc(). 


Includes: 
¢ #include <stdlib.h> 


See also: 


calloc 
malloc 
realloc 


man(3) — free 


fscanf 
Scan from a stream. 





int fscanf(FULE *stream, const char *format, ...) 
Includes: 
¢ #include <stdio.h> 
See also: 
man(3) — fscanf 


fseek 


fstat 
Obtain the stats of an open file. 


int fstat(int fd, struct stat *buf) 
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See also: 
man(2) — fstat 


fwrite 
Write data to an output stream. 





size t fwrite(const void *ptr, size t size, size t nmemb, FILE *stream) 
Includes: 
¢ #include <stdio.h> 
See also: 
man(3) — fwrite 


gettimeofday 
Get the current time. 


int gettimeofday(struct timeval *tv, struct timezone *tz) 


Return the current time of day as a struct timeval. This structure contains the following 
fields: 


* time t tv_sec — Seconds since epoch. 
* suseconds_t tv_usec — Microseconds within current second. 


A sample set of C functions is available here <insert URL> that provides some simple 
routines for working with struct timeval including: 


° struct timeval timeval_add(struct timeval *a, struct timeval *b) — Add 


two time values together. 








° void timeval addMsecs(struct timeval *a, uint32 t msecs) — Add 


milliseconds to time value. 





* uint32 t timeval durationBeforeNow(struct timeval *a) — Determine how 
many milliseconds the supplied time value was in the past. 























* uint32 t timeval durationFromNow(struct timeval *a) — Determine how 
many milliseconds the given future time value will be from now or 0 if it has 
already passed. 


* struct timeval timeval_ sub(struct timeval *a, struct timeval *b) — 
Subtract one time value from another. The first parameter should be further 
along the time line (sooner) than the second (later). 





* uint32 t timeval_toMsecs(struct timeval *a) — Return the number of 
milliseconds within the time value. 
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Includes: 
¢ #include <sys/time.h> 


See also: 


settimeofday 
Timers and time 
man(2) — gettimeofday 





gmtime 
Break down a time into its components based on UTC. 


struct tm *gmtime(const time _t *timep) 
struct tm *gmtime r(const time _t *timep, struct tm *result) 


The time_t value can be obtained from a call to time(). 
Includes: 
¢ #include <time.h> 


See also: 


Timers and time 
time 


man(3) — gmtime 


isalnum 
Determine if a character is alpha/numeric. 


int isalnum(int c) 
Includes: 
¢ #include <ctype.h> 
See also: 
man(3) — isalnum 


isalpha 
Determine if a character is an alpha. 


int isalpha(int c) 
Includes: 


¢ #include <ctype.h> 
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See also: 

man(3) — isalpha 
isascii 
int isascii(int c) 
Includes: 


¢ #include <ctype.h> 


See also: 
man(3) — isascii 
isblank 


int isblank(int c) 
Includes: 
¢ #include <ctype.h> 

See also: 

man(3) — isblank 
isdigit 
int isdigit(int c) 
Includes: 


¢ #include <ctype.h> 


See also: 
man(3) — isdigit 
islower 


int islower(int c) 
Includes: 
¢ #include <ctype.h> 
See also: 
man(3) — islower 


isprint 


int isprint(int c) 
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Includes: 


¢ #include <ctype.h> 


See also: 
man(3) — isprint 
ispunct 


int ispunct (int c) 
Includes: 
¢ #include <ctype.h> 
See also: 
man(3) — ispunct 


isspace 
int isspace(int c) 


Includes: 
¢ #include <ctype.h> 
See also: 
man(3) — isspace 


isupper 
int isupper(int c) 


Includes: 
¢ #include <ctype.h> 


See also: 


man(3) — isupper 


itoa 
See also: 


man(3) — 


labs 


long labs(long val) 
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Includes: 
¢« #include <stdlib.h> 


See also: 
man(3) — labs 
div 


ldiv_t ldiv(long numerator, long demominator) 
Includes: 
¢ #include <stdlib.h> 


See also: 
man(3) — Idiv 
localtime 


struct tm *localtime(const time_t *timep) 
struct tm *localtime _r(const time t *timep, struct tm *result) 


Includes: 
¢ #include <time.h> 


See also: 


Timers and time 


man(3) — localtime 


malloc 
Allocate storage from the heap. 


void *malloc(size t n) 
When no longer needed, the storage should be returned by a call to free(). 
Includes: 

¢ #include <stdlib.h> 


See also: 


calloc 
free 
realloc 


man(3) — malloc 


memchr 
Find a character/byte within a given piece of memory. 
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void *memchr(const void *s, int c, size t n) 
Includes: 
¢ #include <string.h> 
See also: 
man(3) — memchr 


memcmp 
Compare the content of one piece of memory against another. 


int memcmp(const void *ml, const void *m2, size t n) 
Includes: 
¢ #include <string.h> 
See also: 
man(3) — memcmp 


memcpy 
Copy one piece of memory to another. 


int memcpy(void *dest, const void *src, size t n) 
Includes: 
¢ #include <string.h> 
See also: 
man(3) — memcpy 


memmove 
Copy memory from one place to another handling overlaps. 


void *memmove (void *dst, const void *src, size t n) 


Includes: 
¢ #include <string.h> 
See also: 
man(3) — memmove 


memrchr 
Find a character within a piece of memory searching backwards from the end. 
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void *memrchr(const void *s, int c, size t n) 
Includes: 
¢ #include <string.h> 
See also: 
man(3) — memrchr 


memset 
Set a piece of memory to a specific value. 


void *memset (void *dst, int c, size t n) 
Includes: 
¢ #include <string.h> 
See also: 
man(3) — memset 


mktime 
time t mktime(struct tm *tm) 


Includes: 
¢ #include <time.h> 


See also: 


Timers and time 


man(3) — mktime 


open 

Open a file. 

int open(const char *path, int oflag, ...) 
The path is the path to the file to open. 


The of1ag is a Set if bitwise flags used to control how the file is opened. One of the 
following must be supplied: 


- O RDONLY 
- O WRONLY 
- O RDWR 


In addition, the following combination may also be supplied: 
* O APPEND 
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- O CREAT 


* O EXCL 
* O _TRUNC 
For example: 


struct stat statBuf; 


int 


fd = open(path, O _RDONLY); 


fstat(fd, &statBuf) ; 

data = malloc(statBuf.st_size); 
read(fd, data, statBuf.st_ size); 
close (fd); 


On 


return, the value is the handle to the open file descriptor or -1 if there was an error in 


which case "errno" will be set. 


Includes: 


¢ #include <fcntl.h> 


See also: 


close 
stat 
fstat 
read 
write 


man(3) — open 


open_memstream 
Create a dynamic buffer for writing. 


FIL! 





E *open_memstream(char **ptr, size t *sizeloc) 


The return is a FILE pointer that can be used to write into. After an fclose() oran 
fflush() the ptr and sizeloc are updated to point to the buffer and size. The storage 
should be released with a call to free () when done. 


Includes: 


¢ #include <stdio.h> 


See also: 


man(3) — open_memstream 





printf 
Print a formatted string to stdout. 
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int printf (const char *format, ...) 
Includes: 


¢« #include <stdio.h> 


See also: 

fprintf 

man(3) — printf 
qsort 


void gqsort ( 
void base, 
size_t nmemb, 
size t size, 
int (*compar) (const void *, const void *)) 


Includes: 


¢« #include <stdlib.h> 


See also: 
man(3) — qsort 
rand 


Generate a random number. 


int rand() 


Return a random number. Note that the result is an integer which is signed. 
Includes: 


¢ #include <stdlib.h> 


See also: 
man(3) — rand 
read 


Read data from a file or socket. 


ssize t read(int fd, void *buf, size_t nbytes) 
Includes: 
¢ #include <unistd.h> 
See also: 
man(3) — read 
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readdir 


realloc 
Reallocate a portion of malloced data to a new size. 


void *realloc(void *originalData, size t newSize) 
Includes: 
¢ #include <stdlib.h> 


See also: 


free 
calloc 
malloc 


man(3) — realloc 


scanf 
int scanf(const char *format, ...) 


Includes: 
¢ #include <stdio.h> 
See also: 
man(3) — scanf 


setenv 
Set the value of an environment variable. 


int setenv(const char *name, const char *value, int overwrite) 


setlocale 
char *setlocale(int category, const char *locale) 


See also: 
man(3) — setlocale 


settimeofday 
Set the current time of day. 


int settimeofday(const struct timeval *tv, const struct timezone *tz) 
Includes: 


¢ #include <sys/time.h> 
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See also: 


gettimeofday 
Timers and time 
man(2) — settimeofday 





sprintf 
Perform a printf to a region of memory. 


int sprintf(char *out, const char *format, ...) 
Includes: 


¢ #include <stdio.h> 


See also: 
man(3) — sprintf 
srand 


Set the random number seed. 


void srand(unsigned int seed) 
See also: 
man(3) — srand 


sscanf 
int sscanf(const char *str, const char *format, 


See also: 
man(3) — scanf 


stat 
Get the status of a file by path. 


int stat(const char *path, struct stat *buf) 
See also: 
man(2) — stat 


strcasecmp 
int strcasecmp(const char *sl, const char *s2) 


See also: 
man(3) — strcasecmp 
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strcasestr 
char *strcasestr(const char *haystack, const char *needle) 


See also: 


man(3) — strcasestr 


strcat 
Concatenate two strings together. 


char *strcat(char *dst, const char *src) 
See also: 
man(3) — strcat 


strchr 
Search for a character in a string. 


char *strchr(const char *s, int c) 
See also: 
man(3) — strchr 


strcmp 
Compare two strings. 


int stremp(const char *sl, const char *s2) 
See also: 
man(3) — strcmp 


strcoll 
int strcoll(const char *sl, const char *s2) 


See also: 


man(3) — strcoll 


strcpy 
Copy a null terminated string. 


char *strcpy(char *dst, const char *src) 


Page 713 


Copy the null terminated string pointed to by "src" to the storage area pointed to by 
"ast". The destination must have enough storage to hold the source string including its 
null terminator. 


Includes: 
¢ #include <string.h> 
See also: 
man(3) — strcpy 


strcspn 
size t strcespn(const char *s, const char *reject) 


See also: 
man(3) — strespn 


strdup 
Duplicate the null terminate string via malloc(). 


char *strdup(const char *s) 


A simple but powerful function. The null terminated string supplied as an input 
parameter is duplicated bu mallocing enough storage to hold a copy and then the string 
is actually copied. The returned value is a pointer to the new string copy. The storage 
for the new string should eventually be released with a call to free(). 


See also: 
man(3) — strdup 


strerror 
Convert an error code into a string representation. 


char *strerror(int errnum) 


Includes: 
¢ #include <string.h> 
¢ #include <errno.h> 
See also: 
man(3) — strerror 


strftime 
size t strftime(char *s, size t max, const char *format, const struct tm *tm) 
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See also: 
man(3) — strftime 


stricat 
size t strlcat(char *dst, const char *src, size_t size) 


See also: 
man(3) — stricat 


stricpy 


size_t strlicpy(char *dst, const char *src, size t size) 
See also: 
man(3) — strlcpy 


strlen 
Return the length of a null terminated string. 


size t strlen(const char *s) 
Return the length of a null terminated string. 
See also: 

man(3) — strlen 


strncasecmp 
int strncasecmp(const char *sl, const char *s2, size t n) 


See also: 


man(3) — strncasecmp 





strncat 
char *strncat(char *dst, const char *src, size t count) 


See also: 
man(3) — strncat 


strncmp 
int strncmp(const char *sl, const char *s2, size t n) 


See also: 


Page 715 


. man(3) — strncmp 


strncpy 


char *strncpy(char *dst, const char *src, size t n) 
See also: 
. man(3) — strncpy 


strndup 


char *strdup(const char *s) 
See also: 
. man(3) — strndup 


strnien 
size t strnlen(const char *s, size t maxlen) 


See also: 
. man(3) — strnien 


strrchr 
char *strrchr(const char *s, int c) 


See also: 
. man(3) — strrchr 


strsep 
char *strsep(char **stringp, const char *delim) 


See also: 
. man(3) — strsep 


strspn 
size_t strspn(const char *s, const char *accept) 


See also: 
. man(3) — strspn 


strstr 
char *strstr(const char *haystack, const char *needle) 


See also: 
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man(3) — strstr 


strtod 


double strtod(const char *nptr, char **endptr) 
See also: 
man(3) — strtod 


strtof 


float strtof(const char *nptr, char **endptr) 
See also: 
man(3) — strtof 


strtol 
long strtol(const char *str, char **endptr, int base) 


See also: 
man(3) — strtol 


strtoul 
unsigned long strtoul(const char *nptr, char **endptr, int base) 


See also: 
man(3) — strtoul 


strupr 
See also: 


man(3) — strupr 


time 
Retrieve the current time as the number of seconds since the epoch. 


time t time(time t *t) 


If tis supplied, then the time will be stored at that location. If NULL, the time will only be 
returned as a return value. 


Includes: 


¢ #include <time.h> 


Page 717 


See also: 


Timers and time 


man(2) — time 


times 


clock _t times(struct tms *buffer) 
The struct tms contains: 
* clock_t tms_utime — user time 
* clock_t tms_stime — system time 
¢ clock_t tms_cutime — user time children 
* clock_t tms_cstime — system time children 


See also: 


Timers and time 


man(3) — times 


toascii 


int toascii(int c) 
See also: 
man(3) — toascii 


tolower 


int tolower(int c) 
See also: 
man(3) — tolower 


toupper 
int toupper(int c) 


See also: 
man(3) — toupper 


tzset 
Use the time zone information found in the TZ environment variable. 


void tzset() 


Examples ... 


CST+6 
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for example, in code: 


setenv ("TZ", "CST+6", 1); 
tzset(); 


See also: 


man(3) — tzset 
Specifying the Time Zone with TZ 





ungetc 
int ungetc(int c, FILE *fp) 





See also: 
man(3) — ungetc 


utoa 
See also: 


man(3) — utoa 


vprintf 


int vprintf£(const char *format, va_list ap) 
Includes: 
¢ #include <stdio.h> 
See also: 
man(3) — vrprintf 


vscanf 
int vscanf(const char *format, va_list ap) 


Includes: 
¢ #include <stdio.h> 
See also: 
man(3) — vscanf 


write 
ssize t write(int fd, const void *buf, size t nbyte) 


See also: 
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man(3) — write 


SPIFFs API 
See also: 


Spiffs File System 
Github: pellepl/spiffs 





SPIFFS_check 
Perform a consistency check on the file system. 


s32_t SPIFFS check(spiffs *fs) 


* fs -— The file system to be checked for consistency. 


SPIFFS_clearerr 
Clear the last error. 


void SPIFFS clearerr(spiffs *fs) 


* fs —The file system reference. 


SPIFFS_close 
Close a previously opened file. 


s32_t SPIFFS close(spiffs *fs, spiffs file fh) 
¢ +£s-— The file system reference. 


* f£h—Ahandle to a previously opened file. 


SPIFFS_closedir 
Close a previously opened directory. 


s32_t SPIFFS closedir(spiffs_ DIR *dir) 


* dir—Adirectory previously opened by sPIFrrs_opendir(). 


SPIFFS_creat 
Create a new file. 


s32_t SPIFFS creat(spiffs *fs, const char *path, spiffs_ mode mode) 
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¢ +£s-— The file system reference. 
* path — The path to the new file. 


* mode — Ignored. 


SPIFFS_eof 
Determine if we are at the end of the file. 


s32_t SPIFFS eof(spiffs *fs, spiffs file fh) 
¢ +£s-— The file system reference. 


¢ f£h—Ahandle to an open file. 


SPIFFS_errno 
Returns the last error detected by performing a SPIFFs API call. 


s32_t SPIFFS errno(spiffs *fs) 
¢ +£s-— The file system reference. 
The defined codes are: 
* SPIFFS oK—0O 
* SPIFFS ERR NOT MOUNTED — -10000 
* SPIFFS ERR FULL —-10001 —-ENOSPC 
* SPIFFS ERR NOT FOUND —-10002 —- ENOENT 








* SPIFFS ERR END OF OBJECT —-10003 














* SPIFFS ERR DELETED — -10004 














* SPIFFS ERR NOT FINALIZED —-10005 








* SPIFFS ERR NOT INDEX —-10006 








* SPIFFS ERR OUT OF FILE DEsScs —-10007 — ENFILE 

















* SPIFFS ERR FILE CLOSED —-10008 

















* SPIFFS ERR FILE DELETED —-10009 




















* SPIFFS ERR BAD DESCRIPTOR —-10010 


* SPIFFS ERR IS INDEX —-10011 

















* SPIFFS ERR IS FREE —-10012 
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op) 








n 











wn 














n 














op) 











n 











op) 


PIFFS ERR INDEX LU—-1001 














n 


PIFFS ERR INDEX INVALID — 


n 

















op) 








n 


PIFFS ERR CONFLICTING NAMI 


PIFFS ERR INDEX SPAN MISMATCH — -10013 
PIFFS ERR DATA SPAN MISMATCH — -10014 
PIFFS ERR INDEX REF FREE —-10015 
PIFFS ERR INDEX REF LU —-10016 

PIFFS ERR INDEX REF INVALID—-10017 


PIFFS ERR INDEX FREE —-10018 


9 
-10020 


PIFFS ERR NOT WRITABLE — -10021 


PIFFS ERR NOT READABLE — -10022 


E — -10023 

















SPIFFS ERR _NoT A FS—-1002 


SPIFFS ERR NOT CONFIGURED — -10024 


5 — Commonly seen when we mount a file system 


at an SPI address range and the data found on flash isn't formatted as a SPIFFs 


file system. We can then use 
the mount again. 














wn 














n 




















n 








n 


n 











op) 











n 











n 





n 


PIFFS ERR NAME TOO LONG — 





n 


PIFFS ERR IX MAP UNMAPPED 








op) 


PIFFS ERR IX MAP MAPPED — 











n 


PIFFS ERR IX MAP BAD RANGI 


SPIFFS format () to format the data and attempt 


SPIFFS ERR MOUNTED — -10026 
SPIFFS ERR ERASE FAIL —-10027 


PIFFS ERR MAGIC NOT POSSIBLE — -10028 





PIFFS ERR NO DELETED BLOCKS —-10029 
PIFFS ERR FILE Exists —-10030 — EEXIST 
PIFFS ERR NOT A FILE —-10031 — EBADF 
PIFFS ERR RO NOT IMPL—-10032 
PIFFS ERR RO ABORTED OPERATION — -10033 
PIFFS ERR PROBE TOO FEW BLOCKS — -10034 


PIFFS ERR PROBE NOT A FS—-10035 


-10036 

— -10037 
-10038 

E — -10039 











* SPIFFS ERR INTERNAL — -10050 











* SPIFFS ERR TEST—-10100 





SPIFFS_fflush 
Flush the content of a file to flash. 


s32_t SPIFFS fflush(spiffs *fs, spiffs file fh) 
¢ £s—Areference to the file system structure. 


¢ +£h—Afile handle to a previously opened file. 


SPIFFS_format 
Format the file system. 


s32_t SPIFFS format(spiffs *fs) 


¢ £s—Areference to the file system structure. 


SPIFFS_fremove 
Remove a file by file handle. 


s32_t SPIFFS fremove(spiffs *fs, spiffs file fh) 
* £s—Areference to the file system structure. 


¢ +£h—Afile handle to a previously opened file. 


SPIFFS_fstat 


s32_t SPIFFS fstat(spiffs *fs, spiffs file fh, spiffs stat *s) 
¢ £s —Reference to the file system structure. 
¢ +£h-—Afile handle that has been previously opened. 
* s- Apointer to a spiffs stat data structure that will be populated. 
° obj_id 
© size —The size of the file. 


© type — The type of entry. Possibilities are: 














=" SPIFFS TYPE FILE—Entry is a file. 
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™ SPIFFS TYPE DIR—Entry is a directory. 


=" SPIFFS TYPE HARD LINK — Entry is a hard link. 











=" SPIFFS TYPE SOFT LINK — Entry is a soft link. 
° pix — Page index. 


° name — The name of the file. 


SPIFFS_gc 
Perform a garbage collection. 


$32 _t SPIFFS gc(spiffs *fs, u32_t size) 
¢ £s — Reference to the file system structure. 


* size — The amount of space being sought. 


SPIFFS_gc_quick 


s32_t SPIFFS gc _quick(spiffs *fs, ulé_t max free pages) 
¢ £s —Reference to the file system structure. 


* max_free_pages 


SPIFFS_info 
Determine information about the file system. 


s32_t SPIFFS info(spiffs *fs, u32_t *total, u32_t *used) 
* £s—Areference to the file system structure. 
* total —The total size of the file system. 


* used — The number of bytes used from the file system. 


SPIFFS_lseek 


Change the file pointer. 
s32_t SPIFFS_1lseek ( 
spiffs *fs, 
spiffs file fh, 
S32 “C.OLts; 
int whence) 


¢ £s—Areference to the file system structure. 
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fh — A file handle to an open file. 
offs — The numeric by which to change the file pointer. 


whence — An indication of how to change the file pointer: 








© SPIFFS SEEK SET — Change the file pointer to an absolute value. 








© SPIFFS SEEK CUR — Change the file pointer with reference to its current value. 














© SPIFFS SEEK END — Change the file pointer relative to the end of the file. 








SPIFFS_mount 
Mount a file system specifying the flash memory address range. 


s32_t SPIFFS_ mount ( 
spiffs *fs, 


spiffs config *config, 
u8 _t *work, 
u8 _t *fd_space, 


u32_ t fd_space size, 


void *cache, 


u32_t cache size, 
spiffs check callback check _cb_ f) 





fs — The File System control structure. 
config — The physical and logical configuration of the file system. 
work —A memory buffer that should be 2 * log page size used for local work. 


fd_space —A pointer to memory to hold file descriptor working space. Typically 
sized at the max number of open file descriptors * sizeof(uint32). 


fd_space_size — The size of the file descriptor space. 
cache — Cache memory. 


cache size — The size of cache memory. An example would be (log page size + 
32) x 4. 


check cb _f — Callback function invoked to report file system inconsistencies. 
Can be NULL. 


SPIFFS_mounted 
Determine whether or not the file system is mounted. 


u8_t SPIFFS mounted(spiffs *fs) 
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* fs — The file system to be checked. 


SPIFFS_open 
Open a new or existing file. 
spiffs file SPIFFS open ( 
spiffs *fs, 
const char *path, 
spiffs flags flags, 
spiffs mode mode) 
* fs —The reference to the file system control data. 
* path — The path of the file to be opened or created. 
* flags — Flags controlling access to the file. 
o SPIFFS_O_ APPEND 
o SPIFFS_O CREAT 
o SPIFFS_O DIRECT 
o SPIFFS_O EXCL 
o SPIFFS_O RDONLY 
o SPIFFS_O RDWR 
o SPIFFS_O_TRUNC 
o SPIFFS_O_WRONLY 


* mode — Ignored. 


SPIFFS_open_by_dirent 
Open a file by its directory entry. 
spiffs file SPIFFS open by dirent ( 
spitis -<£s, 
struct spiffs dirent *entry, 
spiffs flags flags, 
spiffs mode mode) 
¢ £s— The reference to the file system control data. 
* entry — The directory entry to be opened. 
* flags — Flags controlling access to the file. 
o SPIFFS_O APPEND 


o SPIFFS_O_DIRECT 
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(e) 


(e) 


SPIFFS_O_EXCL 
SPIFFS_O_RDONLY 
SPIFFS_O_RDWR 
SPIFFS_O_TRUNC 
SPIFFS_O_WRONLY 


* mode — Ignored. 


SPIFFS_open_by_page 
Open a file given the page it exists within the file system. 


spiffs file SPIFFS open by page ( 
spiffs *fs, 


spiffs page ix page ix, 


spiffs flags flags, 


spiffs mode mode) 


¢ £s— The reference to the file system control data. 


* page ix — The page to open. 


* flags — Flags controlling access to the file. 


(e) 


(e) 


(e) 


(e) 


(e) 


(e) 


(e) 


SPIFFS_O_APPEND 
SPIFFS_O DIRECT 
SPIFFS_O_EXCL 
SPIFFS_O_RDONLY 
SPIFFS_O_RDWR 
SPIFFS_O_TRUNC 
SPIFFS_O_WRONLY 


* mode — Ignored. 


SPIFFS_opendir 
Open a directory to work with it. 


spiffs DIR *SPIFFS opendir(spiffs *fs, const char *name, spiffs DIR *dir) 


¢ £s— The reference to the file system control data. 


* name — The name of a directory. 
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* dir -— Pointer to the directory structure to be populated. 


The return is an opaque data type referring to the directory. 


SPIFFS_read 


Read data from an open file. 


s32_t SPIFFS_ read ( 
spiffs *fs, 
spiffs file fh, 
void *buf, s32 t len) 


¢ £s —Reference to the file system structure. 


¢ £h-— The file handle to a previously opened file. 


* buf — The buffer into which to read the data. 


* 1en—The size of the buffer in bytes. 


The return is the number of bytes read or -1 if there was an error. 


SPIFFS_readdir 
Read the content of a directory. 


struct spiffs dirent *SPIFFS readdir(spiffs DIR *dir, struct spiffs_dirent *dirent) 


* dir -— The directory to be read. An opaque data type returned by 
SPIFFS opendir(). 


* dirent —Adirectory entry that was read. 


(0) 


(e) 


(e) 


(e) 


(e) 


objid —Internal id of the file. 


name — Name of the file. 


type 


S 


S 


S 


S 


(spit 


Fs obj type) — Type of the file. Possibilities are: 








PIFFS T 
PIFFS T 
PIFFS T 


PIFFS T 





YPE 


YF 


YF 


YF 


FILE — Entry is a file. 








PE 


au 


PF 


= 
aay 








D] 


= 
au 





_DIR— Entry is a directory. 


_HARD LINK — Entry is a hard link. 





E SOFT LINK — Entry is a soft link. 


size — Size of the file. 


pix — Page index of the file. 


Return NULL on error of end of stream of entries. 
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SPIFFS_remove 
Remove a file by path. 


s32_t SPIFFS remove(spiffs *fs, const char *path) 
¢ £s —Reference to the file system structure. 


* path — The path to the file to be removed. 


SPIFFS_rename 
Rename a file. 


s32_t SPIFFS rename(spiffs *fs, const char *oldPath, const char *newPath) 
* fs —Reference to the file system structure. 


* oldPath — The old path of the file. 





* newPath — The new path of the file. 


SPIFFS_stat 
Get information about a file. 


$32 t SPIFFS stat(spiffs *fs, const char *path, spiffs stat *s) 
¢ £s — Reference to the file system structure. 
* path — The path to the file to be examined. 
¢ s- Apointer toa spiffs stat data structure that will be populated. 
° Obj_id 
© size —The size of the file. 


© type — The type of entry. Possibilities are: 











=" SPIFFS TYPE FILE—Entry is a file. 


=" SPIFFS TYPE DIR—Entry is a directory. 


=" SPIFFS TYPE HARD LINK — Entry is a hard link. 

















=" SPIFFS TYPE SOFT LINK — Entry is a soft link. 
° pix — Page index. 


° name — The name of the file. 
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SPIFFS_tell 
Find position within file. 


s32_t SPIFFS tell(spiffs *fs, spiffs file fh) 
¢ £s —Reference to the file system structure. 


¢ £h-—An open file handle. 


SPIFFS_unmount 
Un-mount a previously mounted file system. 


void SPIFFS unmount (spiffs *fs) 
The fs is the file system structure previously populated from a sPIFFS mount () Call. 


See also: 


SPIFFS_mount 


SPIFFS_write 
Write data into a file. 


s32_t SPIFFS write ( 
spiffs *fs, 
spiffs file fh, 
void *buf, s32 t len) 


* £s—Areference to the file system structure. 

¢ +£h—Afile handle previously opened. 

* buf —A pointer to a buffer containing the data to be written. 
* len —The length of the data to write. 


The return is the number of bytes actually written or -1 if there was an error. 


Eclipse Paho - MQTT Embedded C 

The Eclipse Paho project is a collection of implementations of MQTT based functions 
governed by the Eclipse foundation. Included in this suite is an embedded C 
implementation which is an MQTT client written in as vanilla a C language as is 
possible. 

See also: 


MQTT 
Eclipse paho 
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Eclipse Paho — embedded C 
Eclipse Paho 





MQTTClientInit 
Initialize an MQTTClient. 


void MOTTClientInit ( 
MOTTClient* c, 
Network *network, 
unsigned int command_timeout_ms, 
unsigned char *sendbuf, 
size_t sendbuf_ size, 
unsigned char *readbuf, 
size t readbuf_size) 


The network is a populated connection to the target broker. 


MQTTConnect 
Connect to a remote MQTT broker. 


int MOQTTConnect ( 
MOTTClient *c, 
MOTTPacket_connectData *options) 








The options structure should always be initialized through assignment from 
MQTTPacket_connectData_initializer. For example: 


MOTTPacket_connectionData data = MOTTPacket_connectData_ initializer 


Once populated, we can then over-ride some of the defaults to reflect our desired 
changes. Within the object we have: 


* MOTTString client1p—Ahn indenitication used by this client. 


* unsigned short keepAliveInterval — The keep-alive interval for the connection 
in seconds. If the client doesn't communicate from its last message within this 
interval then the broker can consider the client lost. The special value of 0 
means that there will be no keep-alive checking. 


* unsigned char cleansession — Set to 1 to begin a clean session otherwise 
supply 0. 

* unsigned char willFlag 

¢ MQTTPacket_willOptions will 


* MOTTString username — The user name passed for authentication. 











* MOQTTString password — The password passed for the user for authentication. 
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The return codes from this call are: 
¢ SUCCESS (0) — connected successfully. 
¢ FAILURE (-1) — General failure. 
¢ BUFFER_OVERFLOW (-2) — Buffer overflow. 
Other than these, the returns are MQTT CONNACK responses which are: 
¢ 1-—-— Unacceptable protocol version. 
¢ 2-Client identifier rejected. 
¢ 3 - Server unavailable. 
e 4-—- Bad username or password. 
¢ 5-—Not authorized. 


MQTTDisconnect 
Disconnect from the broker. 


int MOTTDisconnect (MOTTClient* c) 


Followiing a successful previous call to MoTtconnect (), this function disconnects us 
from the broker. 


MQTTPublish 
Publish a message to the broker. 
int MQTTPublish ( 
MQOTTClient *c, 
const char *topicName, 
MOTTMessage *message) 











The mottTMessage Is a Structure that reflects the message to be published. It includes: 
* enum QoS gos — The desired quality of service of the published message. 
* unsigned char retained — Not used in a publish. 
* unsigned char dup — Not used in a publish. 
* unsigned short id—The identity of this message. 
* void *payload— The payload content of this message. 


* size t payloadlen— The length of the message payload. 


MQTTRun 


void MOTTRun(void* parm) 
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MQTTSubscribe 
Subscribe to a topic. 
int MOQTTSubscribe ( 


MOTTClient *c, 
const char *topicFilter, 





enum QoS qos, 
messageHandler messageHandler) 





The messageHandler Is a function that is called when a new message is received as 
published by the broker. The signature of the function is: 


void func(MessageData *data) 
The MessageData contains: 


* MOQTTString *topicName — The topic on which the message was published. To 
examine the topicName, we should use the form topicName->lenstring.len and 


topicName->lenstring.data. 


MOTTMessage *message — The content of the message received. 





The MOTTMesage contains: 
* enum QoS qos — What is the quality of service. 
* unsigned char retained — Was this a retained message. 
* unsigned char dup — Was this message sent more than once. 
* unsigned short id—The id of the message. 
* void *payload— The payload data of the message. 


* size t payloadlen— The length of the payload data. 


MQTTUnsubscribe 
Unsubscribe from receiving further publications on the topic. 
int MOTTUnsubscribe ( 


MQOTTClient *c, 
const char* topicFilter) 





MQTTYield 

int MOTTYield( 
MOTTClient *c, 
int timeout_ms) 
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NetworkConnect 
Connect to an MQTT broker 


int NetworkConnect (Network *network, char *address, int port) 


If the return is 0, then the connection succeeded. 


Arduino ESP32 Libraries 


Arduino WiFi library 
The Arduino has a WiFi library for use with its WiFi shield. A library with a similar 
interface has been supplied for the Arduino environment for the ESP32. 


To use the ESP32 WiFi library you must include its header: 
#include <WiFi.h> 

We must also call 

initWiFi () 

and 

startWiFi () 


before using any of the other WiFi functions in the Arduino library. It is recommended 
NOT to mix WiFi setup in ESP-IDF with WiFi setup in the Arduino environment. 





To be a station and connect to an access point, execute a call to WiFi.begin(ssid, 
password). Now we need to to poll wiri.status(). When this returns wi. CcoNNECTED, 
then we are connected to the network. 














To set up an access point, we would call wiri.softaP() supplying the SSID and 
password information. 


Here is an example of us connecting as a station: 


WiFi.mode (WIFI STA); 

WiFi.begin(SSID, PASSWORD) ; 

if (WiFi.waitForConnectResult() != WL CONNECTED) { 
Seriall.printin ("Failed") ; 














return; 


} 
WiFi.printDiag(Seriall); 
// We are now connected as a station 


See also: 


. Arduino WiFiClient 
. Arduino WiFiServer 


. Arduino WiFi library 
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WiFi.begin 
Start a WiFi connection as a station. 


int begin ( 
const char *ssid, 
const char *passPhrase=NULL, 
int32_t channel=0, 
uint8 t bssid[6]=NULL) 


int begin ( 
char *ssid, 
char *passPhrase=NULL, 
int32_t channel=0, 
uint8 t bssid[6]=NULL) 





Begin a WiFi connection as a station. The ssid parameter is mandatory but the others 


can be left as default. The return value is our current connection status. 


Includes: 
¢ WiIFISTA.h 


WiFi.beingSmartConfig 
bool beginSmartConfig() 





WiFi.beginWPSConfig 
bool beginWPSConfig() 


WiFi.BSSID 
Retrieve the current BSSID. 


uint8 t BSSID() 
uint8 t *BSSID(uint8 t networkItem) 


Retrieve the current BSSID. 


Includes: 
¢ WiFiScan.h 
¢ WiIFISTA.h 


WiFi.BSS|Dstr 


Retrieve the current BSSID as a string representation. 
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String BSSIDstr() 
String BSSIDstr(uint8 t networkItem) 


Retrieve the current BSSID as a string representation. 


Includes: 
¢ WiFiScan.h 
¢ WiIFISTA.h 


WiFi.channel 
Retrieve the current channel. 


int32 t channel () 
int32 t channel (uint8 t networkItem) 


Retrieve the current channel. 
Includes: 

¢ WiFiScan.h 

¢ WiFiGeneric.h 


WiFi. config 
Set the WiFi connection configuration. 


void config(IPAddress local ip, IPAddress gateway, 
void config(IPAddress local ip, IPAddress gateway, 


IPAddress subnet) 
IPAddress subnet, 


IPAddress dns) 


Set the configuration of the WiFi using static parameters. This disables DHCP. 


Includes: 
¢ WiIFISTA.h 


WiFi.disconnect 
Disconnect from an access point. 


int disconnect (bool wifiOff = false) 


Disconnect from the current access point. 


Includes: 
¢ WiIFISTA.h 


WiFi.dnsIP 
Includes: 
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¢ WIFISTA.h 


WiFi.enableAP 
Includes: 


¢ WiFiGeneric.h 


WiFi.enableSTA 
Includes: 


¢ WiFiGeneric.h 


WiFi.encryptionType 
Return the encryption type of the scanned WiFi access point. 





uint8 t encryptionType(uint8 t networkItem) 
Return the encryption type of the scanned WiFi access point. 
The values are one of: 
¢ ENC _TYPE_NONE 
* ENC _TYPE_WEP 
¢ ENC_TYPE_TKIP 
¢ ENC _TYPE_CCMP 
« ENC _TYPE_AUTO 
Includes: 
¢ WiFiScan.h 


WiFi.gatewaylP 
Get the IP address of the station gateway. 


IPAddress gatewayIP() 
Retrieve the IP address of the station gateway. 
Includes: 

¢ WiFISTA.h 


WiFi.getAutoConnect 
Includes: 


¢ WIFISTA.h 
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WiFi.getMode 
Includes: 


¢ WiFiGeneric.h 


WiFi.getNetworkInfo 
Retrieve all the details of the specified scanned networkItem. 





bool getNetworkInfo ( 
uint8 t networkItem, 
String &ssid, 
uint8 t &encryptionType, 
int32_t &RSSI, 
uint8 t *&BSSID, 
int32_ t &channel) 


Retrieve all the details of the specified scanned networkItem. 
Includes: 
¢ WiFiScan.h 


See also: 


WiFi.scanComplete 
WiFi.scanDelete 
WiFi.scanNetworks 


WiFi.hostByName 
Lookup a host by a name. 


int hostByName (const char *hostName, IPAddress &result) 


Look up a host by name and get its IP address. This function returns 1 on success and 
0 on failure. 


Includes: 
¢ WiFiGeneric.h 


WiFi.hostname 

Retrieve and set the hostname used by this station. 
String hostname () 

bool hostname(char *hostName) 


bool hostname (const char *hostName) 
bool hostname (String hostName) 


WiFi.isConnected 
Includes: 
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¢ WIFISTA.h 


WiFi.isHidden 
Determine if the scanned network item is flagged as hidden. 


bool isHiddem(uint8 t networkItem) 


Determine if the scanned network item is flagged as hidden. 


WiFi.locallP 
Get the station IP address. 


IPAddress localIP() 


Get the IP address for the station. There is a separate IP address if the ESP is an 
access point. 


Includes: 
¢ WiFISTA.h 


See also: 


WiFi.softAPIP 


WiFi.macAddress 
Get the station interface MAC address. 


uint_t *macAddress(uint8 t *mac) 
String macAddress () 


Get the station interface MAC address. 
Includes: 
e WiIFISTA.h 


WiFi.mode 
Set the operating mode. 


void mode (WiFiMode mode) 

Set the operating mode of the WiFi. This is one of: 
* WIFI_oFF — Switch off WiFi 
¢ wiFr_sta—Bea WiFi station 


¢ wirr ap —Bea WiFi access point 


Page 739 


* wiFrr ap sta—Be both a WiFi station and a WiFi access point 
See also: 
Includes: 


¢ WiFiGeneric.h 


Wifi.persistent 
Includes: 


¢ WiFiGeneric.h 





WiFi. printDiag 

Log the state of the WiFi connection. 

void printDiag(Print é&dest) 

Log the state of the WiFi connection. We can pass in either Serial or Serial1 as an 
argument to log the data to the Serial port. An example of output is as shown next: 


Mode: STA 

PHY mode: N 

Channel: 7 

AP id: 0 

Status: 5 

Auto connect: 0 

SSID (7): yourSSID 
Passphrase (8): yourPassword 
BSSID set: 0 


Note that the status value is the result of a wifi station get connect status () Call. 
Includes: 
¢ WiFi.h 


WiFi. psk 
Includes: 


¢ WIFISTA.h 
WiFi.RSSI 


Retrieve the RSSI (Received Signal Strength Indicator) value of the scanned network 
item. 


int32 t RSSI(uint8 t networkItem) 


Retrieve the RSSI value of the scanned network item. 
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Includes: 
¢ WiFiScan.h 
¢ WiIFISTA.h 


WiFi.scanComplete 
Determine the status of a previous scan request. 





int8 t scanComplete () 


If the result is >= 0 then this is the number of WiFi access points found. Otherwise, the 
value is less than O and the codes are: 


* SCAN RUNNING —A scan is currently in progress. 
* SCAN FAILD —Ascan failed. 

Includes: 
¢ WiFiScan.h 


See also: 


. WiFi.scanNetworks 
. WiFi.scanDelete 


WiFi.scanDelete 
Delete the results from a previous scan. 





void scanDelete() 


Delete the results from a previous scan. Arequest to scan the network results in the 
allocation of memory. This call releases that memory. 


Includes: 
¢ WiFiScan.h 


See also: 


. WiFi.scanComplete 
. WiFi.scanNetworks 
. WiFi.getNetworkInfo 


WiFi.scanNetworks 
Scan the access points in the environment. 





int8 t scanNetworks (bool async = false, bool show_hidden = false) 
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Scan the access points in the environment. We can either perform this synchronously 
or asynchronously. On a synchronous call, the result is the number of access points 
found. 


Includes: 
¢ WiFiScan.h 


See also: 


. WiFi.scanComplete 
. WiFi.scanDelete 


WiFi.getNetworkInfo 


WiFi.setAutoConnect 
Includes: 


¢ WIFISTA.h 





WiFi.setAutoReconnect 
Includes: 


¢ WIFISTA.h 


WiFi.smartConfigDone 


bool smartConfigDone () 


WiFi.softAP 
Setup an access point. 


void softAP(const char *ssid) 
void softAP(const char *ssid, 
const char *passPhrase, 
int channel=1, 
int ssid_hidden=0) 
The ssid is used to advertize our network. The passPhrase is the password a station 
must supply in order to be authorized to access. 


Includes: 


¢ WIFIAP.h 


WiFi.softAPConfig 
void softAPConfig(IPAddress local_ip, IPAddress gateway, IPAddress subnet) 
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Includes: 
¢ WiFIAP.h 


WiFi.softAPdisconnect 
int softAPdisconnect (bool wifiOff=false) 





Includes: 
¢ WiIFIAP.h 


WiFi.softAPmacAddress 
Get the MAC address of the access point interface. 


uint8 t *softAPmacAddress(uint8 t *mac) 
String softAPmacAddress () 


Get the MAC address of the access point interface. 
Includes: 
¢ WiIFIAP.h 


WiFi.softAPIP 
Get the IP address of the access point interface. 


IPAddress softAPIP() 

Return the IP address of the access point interface. There is a separate IP for the 
station. 

See also: 


WiFi.locallP 


WiFi.SSID 
Retrieve the SSID. 


char *SSID() 
const char *SSID(uint8 t networkItem) 


Here we retrieve the SSID of the current station or the SSID of the scanned network id. 


Includes: 
¢ WiFiScan.h 
¢ WiIFISTA.h 
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WiFi.status 
Retrieve the current WiFi status. 


wl status t status () 
The status returned will be one of: 
¢ WL_IDLE_STATUS (0) 
¢ WL_NO SSID_AVAIL (1) 
¢ WL_SCAN_COMPLETED (2) 
¢ WL_CONNECTED (3) 
¢ WL_CONNECT_FAILED (4) 
¢ WL_CONNECTION_LOST (5) 
¢ WL_DISCONNECTED (6) 
Includes: 


¢ WIFISTA.h 


WiFi.stopSmartConfig 
void stopSmartConfig() 





WiFi.subnetMask 
IPAddress subnetMask() 


Includes: 
¢ WiFISTA.h 


WiFi.waitForConnectResult 


Wait until the WiFi connection has been formed or failed. 


uint8 t waitForConnectResult () 


If we are a station, then block waiting for us to become connected or failed. The return 
code is the status. Specifically, this function watches the status to see when it becomes 





something other than wi DISCONNECTED. Perhaps a more positive form of this function 











would be: 








while (WiFi.status() != WL CONNECTED) 
delay (500); 
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{ 


Serial.print("."); 


} 
Includes: 
¢ WiIFISTA.h 


Arduino WiFiClient 
This library provides TCP connections to a partner. A separate class provides UDP 
communications. 


To use this library, you must include "wiFi.nh". 


We create an instance of this class and then connect to a partner using the connect () 
method. 


WiFiClient 


WiFiClient.available 
Return the amount of data available to be read. 


int available () 


Return the amount of data available to be read. 


WiFiClient.connect 
Connect to the given host at the given port using TCP. 





int connect (const char* host, uintl6 t port) 
int connect (IPAddress ip, uintl6 t port) 


Connect to the given host at the given port using TCP. This function returns 0 ona 
failure. 


WiFiClient.connected 
Determine if we are connected to a partner. 





uint8 t connected () 


Return true if connected and false otherwise. 


WiFiClient.flush 
void flush () 
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WiFiClient.getNoDelay 
bool getNoDelay () 





WiFiClient. peek 
int peek () 


WiFiClient.read 
Read data from the partner. 





int read() 
int read(uint8 t *buf, size t size) 


Read data from the partner. These functions read either a single byte or a sequence of 
bytes from the partner. 


WiFiClient.remotelP 
Retrieve the remote IP address of the connection. 





IPAddress remoteIP() 


Retrieve the remote IP address of the connection. 


WiFiClient.remotePort 
Return the remote port being used in an existing connection. 


uintl6 t remotePort () 


Return the remote port being used in an existing connection. 


WiFiClient.setLocalPortStart 
Set the initial port for allocating local ports for connections. 


void setLocalPortStart(uint16 t port) 


Set the initial port for allocating local ports for connections. 


WiFiClient.setNoDelay 
void setNoDelay (bool nodelay) 





WiFiClient.setOption 


int setOption(int option, int *value) 
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WiFiClient.status 
uint8 t status () 


WiFiClient.stop 
Disconnect a client. 


void stop () 


Disconnect a client. 


WiFiClient.stopAll 
Stop all the connections formed by this WiFi client. 


void stopAll1() 


WiFiClient.write 
Write data to the partner. 





size t write(uint8 t b) 
size t write(const uint8 t *buf, size t size) 
size t write(T& source, size t unitSize); 


Write data to the partner. The first function writes one byte, while the second function 
writes an array of characters. 


Arduino WiFiServer 


WiFiServer 
Create an instance of a Server listening on the supplied port. 


WiFiServer(uintl6 t port) 


Create an instance of a Server listening on the supplied port. Interesting, it appears that 
once we crate a server instance within an ESP8266, there is no way to stop it running. 


WiFiServer.available 
Retrieve a WiFiClient object that can be used for communications. 





WiFiClient available (byte* status) 


Retrieve the corresponding WiFiClient. 
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See also: 


Arduino WiFiClient 


WiFiServer.begin 
Start listening for incoming connections. 


void begin () 
Start listening for incoming connections. Until this method is called, the ESP8266 
doesn't accept incoming connections. Interestingly, once called, there is no obvious 


way to stop listening. The port used for the incoming connections is the one supplied 
when the WiFiServer object was constructed. 


WiFiServer.getNoDelay 





WiFiServer.hasClient 
Return true if we have a client connected. 


bool hasClient() 


WiFiServer.setNoDelay 





WiFiServer.status 


WiFiServer. write 
WARNING!! This method is not implemented. 


size_t write(uint8 t b) 
size_t write(const uint8 t *buffer, size t size) 





Although present on the interface, this method is not yet implemented. 


Arduino |IPAddress 
A representation of an IPAddress. This class has some operator overrides: 


[i] - Get the ith byte of the address. | should be 0-3. 


Arduino SPI 
The Arduino SPI library is loaded from the "spr.n" header file and provides the SPI 
interface. 
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SPI. begin 
Begin to use the SPI bus. 


void begin(int8 t sck=-1, int8 t miso=-1, int8_t mosi=-1, int8 t ss=-1) 


The sck is the pin to use for clock. The miso Is the pin to use for MISO, the mosi is the 
pin to use for MOSI, the ss is the pin to use for SS. 


SP|.beginTransaction 
Begin a transaction. 


void beginTransaction(SPISettings settings) 


The settings is an instance of an SPlSettings object. This is constructed with three 
parameters: 


SPISettings (uint32 t clock, uint8 t bitOrder, uint8 t dataMode) 


This sets the clock speed, bit order and data mode. 


SPl.end 
Stop using the bus. 


void end() 


SPl.endTransaction 
End a transaction. 





void endTransaction (void) 


SPl.setBitOrder 
Set the bit order value. 





void setBitOrder(uint8 t bitOrder) 


SPl.setClockDivider 
Set the clock divider value. 





void setClockDivider (uint32_ t clockDiv) 


SPI.setDataMode 
Set the data mode value. 
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void setDataMode(uint8 t dataMode) 


SPl.setFrequency 
Set the frequency value. 


void setFrequency(uint32 t freq) 


SPI.setHwC 


void setHwCs (bool use) 


SPl.transfer 
uint8 t transfer(uint8 t data) 


SPI.transfer16 
uintl6 t transferl6(uintl6 t data) 


SPI.transfer32 
uint32 t transfer32(uint32_ t data) 


SPl.transferBytes 


void transferBytes(uint8 t * data, uint8 t * out, uint32 t size) 


SPI.transferBits 
void transferBits (uint32 t data, uint32 t * out, uint8 t bits) 





SPI. write 
void write(uint8 t data) 


SPl.wirite16 
void writel6(uint16 t data) 
void writel6(uint16 t data, bool msb) 


SPl.write32 
void write32(uint32 t data) 
void write32(uint32 t data, bool msb) 
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SPl.writeBytes 


void writeBytes(uint8 t * data, uint32 t size) 


SPI.writePattern 
void writePattern(uint8 t * data, uint8 t size, uint32 t repeat) 





Arduino 12C - Wire 

The wire class provides I2C support. In order to use this class, import "wire.h" into 
your sketch. When we use this class, a global instance called "wire" is made available 
to us. One wire is called SCL which provides the clock while the other wire is called 
SDA and is the data bus. On the Arduino, the library supports being either a master or a 
slave however in the current implementation, only being a master is supported. 


To use this class, first we define which pins should be used and then start the service. 


Wire.begin(SDApin, SCLpin); 
To send data, we begin a transmission using beginTransmission(): 
Wire.beginTransmission (deviceAddress) ; 


now we can write some data ... 


Wire.write (value) ; 


and finally complete the transmission: 


Wire.endTransmission(); 

if we wish to receive data from the slave, we can call requestFrom()! 
Wire.requestFrom(deviceAdress, size, true); 

and data can be read using the available() and read () functions. 


See also: 


. Working with I2C 
. Arduino — Wire Library 


Wire. available 
Determine the number of bytes available to read. 


int available (void) 


Determine the number of bytes available to read. 


See also: 


. Wire.read 
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. Wire.requestFrom 


Wire.begin 
Initialize the wire library. 


void begin(int SDApin, int SCLpin) 
) 


void begin 


void begin(uint8 t address) 


void begin(int address) 


( 
( 
( 
( 


Initialize the wire library. When an address is supplied, we are a slave otherwise we are 
amaster. Wecan also specify the pins to be used for SDA and SCL. If we area 
master and no pins are supplied, we will use the default pins. 


WARNING!! — It appears that there is NO support for actually being a slave and only a 
master is supported at this time. 


WARNING!! — In the current code, the address parameter is ignored!! 


See also: 


. Wire.pins 


Wire. beginTransmission 
Beging a transmission block to a slave. 


void beginTransmission(uint8 t address) 
void beginTransmission(int address) 





Begin the notion of sending a transmission to a slave device with the supplied address. 
Further calls to write () will queue data to be transmitted which is finally executed with a 


call to endTransmission(). 


Wire.endTransmission 
End the bracketing of a transmission. 





uint8 t endTransmission (void) // Defaults to sendStop = true 
uint8 t endTransmission(uint8 t sendStop) 





End the bracketing of a transmission and perform the actual transmit. The return codes 
are: 


* o-— Transmitted correctly 
* 2—Received NACK on transmit of address 
* 3— Received NACK on transmit of data 


¢ 4-—line busy 
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Wire.flush 
Discard any un-read or un-written data. 


void TwoWire::flush (void) 


Discard any un-read or un-written data. Acall to available () will return 0 and a call to 
endTransmission() Will transmit no data. 


Wire.onReceive 
A callback when we are in the role of a slave and receive a transmission from a master. 


void onReceive( void (*function) (int numBytes) ) 
A callback when slave receives a transmission from a master. 


WARNING!! — This function is not implemented. 


Wire.onReceiveService 
Not implemented. 





void onReceiveService(uint8 t* inBytes, int numBytes) 
Not implemented. 
WARNING!! — This function is not implemented. 


Wire.onRequest 
A callback invoked when we are in the role of a slave and a master requests data from 
us. 





void onRequest (void (*function) (void) ) 


A callback invoked when we are in the role of a slave and a master requests data from 
us. 


WARNING!! — This function is not implemented. 


Wire.onRequestService 
Not implemented. 


void onRequestService (void) 
Not implemented. 
WARNING!! — This function is not implemented. 
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Wire. peek 
Peek at the next byte. 


int peek (void) 


Peek at the next byte if one is available. A return of -1 if there is no byte available. 


Wire. pins 
WARNING!! - This function has been deprecated in favor of begin(sda, scl). 


Define the default pins for SDA and SCL. 


void pins(int sda, int scl) 
Define the default pins for SDA and SCL. 


See also: 


° Wire.begin 


Wire.read 
Read a single byte. 


int read(void) 
Read a single byte from the bus. A value of -1 is returned if there is no byte available. 


See also: 


. Wire.available 
. Wire.requestFrom 


Wire.requestFrom 
Request data from a slave. 


size t requestFrom(uint8 t address, size t size, bool sendStop) 

uint8 t requestFrom(uint8 t address, uint8 t quantity, uint8 t sendStop) 

uint8 t requestFrom(uint8 t address, uint8 t quantity) 

uint8 t requestFrom(int address, int quantity) 

uint8 t requestFrom(int address, int quantity, int sendStop) 

Request data from a slave. This method should be called when we are playing the role 
of a master. The address parameter defines the slave address for the device that 
should respond. If the sendstop is true, a stop message is transmitted releasing the I2C 
bus. If sendstop is false, a restart message is transmitted preventing another bus 


master from taking control. 
The quantity parameter states how many bytes we wish to receive. 


The return value is the number of bytes that were received. 


Page 754 


See also: 


. Wire.read 
. Wire.available 


Wire.setClock 
Set the clock frequency. 


void setClock(uint32 t frequency) 


Set the clock frequency. Always call setclock() AFTER a call to begin(). 


Wire.write 
Write one or more bytes to the slave. 


size t write(uint8 t data) 
size t write(const uint8 t *data, size t quantity) 


Write one or more bytes to the slave. 


Arduino Ticker library 
This library sets up callback functions that are called after a period of time. To use this 
library you must include "Ticker.h". For example: 


#include <Ticker.h> 


void timerCB() { 
Seriall.printlin("Tick ..."); 
} 


void setup () 

{ 
Seriall.begin (115200); 
ticker.attach(5, timercCB); 
Seriall.printlin("Ticker attached") ; 

} 

Ticker 


An instance of a Ticker object. Commonly this is created as a global such as: 


Ticker myTicker; 


attach 
Attach a callback function to the ticker. 


void attach(float seconds, 
callback_t callback) 
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void attach(float seconds, 

void (*callback) (TArg), 

TArg arg) 
Attach a callback function to the ticker such that the callback is invoked each period of 
seconds. Note that seconds is a float so we can specify values such as 0.1 to indicate 
a Callback every 1/10th of a second (100 milliseconds). 


The callback_t is a defined as: 


void (*callback_t) (void) 


attach _ ms 
Attach a callback function to the ticker. 


void attach_ms(uint32_ t milliseconds, 
callback_t callback) 
void attach_ms(uint32_ t milliseconds, 
void (*callback) (TArg), TArg arg) 
Attach a callback function to the ticker such that the callback is invoked each period of 
milliseconds. Only one attachment can be made to a timer. 


detach 
Detach a ticker from the timer. 


void detach () 


Detach a callback function from the timer. No further callbacks will occur. 


once 
Attach a callback function to the timer for a one-shot firing. 


void once(float seconds, 

callback_t callback) 
void once(float seconds, 

void (*callback) (TArg), 

TArg arg) 
Attach a callback function to the timer for a one-shot firing. Note that seconds is a float 
SO we can specify values such as 0.1 to indicate a callback every 1/10th of a second 
(100 milliseconds). 


once ms 
Attach a callback function to the timer for a one-shot firing. 


void once _ms(uint32_t milliseconds, 
callback_t callback) 
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void once _ms(uint32_t milliseconds, 
void (*callback) (TArg), 
TArg arg) 


Attach a callback function to the timer for a one-shot firing. 


Arduino EEPROM library 
This library allows us to store and retrieve data from storage that persists across a 
device restart. A singleton object called EEPROM is pre-supplied for use. 


EEPROM.begin 
Begin the process of writing or reading from EEPROM. The size is the amount of 


storage we wish to work with. 


void begin(size t size) 


EEPROM.commit 
The changes to the data are committed to EEPROM. A return of true indicates success 
while a return of false indicates a failure. 





bool commit () 


EEPROM.end 
Commits the changes to the data and then releases any local storage. No further reads 
or writes should be attempted until after the next begin() call. 


void end() 


EEPROM.get 
Read a data structure from storage. 


T éget(int address, T &t) 


EEPROM. getDataPtr 
Retrieve a pointer to the storage we are going to read or write. 


uint8 t *getDataPtr () 


EEPROM. put 
Put a data structure to storage. 
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const T &put(int address, const T &t) 


EEPROM.read 
Read a byte from storage. 


uint8 t read(int address) 


EEPROM.write 
Write a byte to storage. 


void write(int address, uint8 t value) 


Arduino SPIFFS 

FS is the File System library which provides the ability to read and write files from within 
the Arduino ESP environment. But wait ... read and write files to where? There are no 
"drives" on an ESP8266. The data for the files is read and written to an area of flash 
memory and since flash is relatively small in size (4MBytes or so max) then that is an 
upper bound of maximum size of the cumulative files ... however, this is still more than 
enough for many usage patterns such as saving state, logs or configuration information. 


SPIFFS.begin 
Begin working with the SPIFFS file system. 


bool begin () 


Returns true of success and false otherwise. 


SPIFFS.open 
Open the named file. 


File open(const char *path, const char *mode) 
File open(const String &path, const char *mode) 


The mode defines how we wish to access the file. The options are: 
¢ x+-—Read the file. The file must exist. 
¢ w-—Write to the file. Truncate the file if it exists. 
* a—Append to the file. 
¢ ++— Read and write the file. 


¢ w+-— Read and write the file. 





¢ a+— Read and write the file. 
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See also: 


. File.close 


SPIFFS.openDir 
Open a directory. 


Dir openDir(const char *path) 
Dir openDir(const String &path) 


SPIFFS.remove 


Remove/delete a file from the file system. 


bool remove(const char *path) 
bool remove(const String &path) 


SPIFFS.rename 
Rename a file. 





bool rename(const char *pathFrom, const char *pathTo) 
bool rename(const String &pathFrom, const String &pathTo) 


File.available 


Return the number of bytes that are available within the file from the current file position 


to its maximum size. 


int available () 


File.close 
Close a previously opened file. 


void close() 


No further reading nor writing should be attempted to be performed. 


File.flush 
Flush the file. 


void flush() 


File.name 
Retrieve the name of the file. 


const char *name() 


Page 759 


File.peek 
Peek at the next byte of data in the file without consuming it. 


int peek () 


File. position 
Retrieve the current file pointer position. 


size_t position () 


File.read 
Read data from the file. 


int read () 
size t read(uint8 t *buf, size t size) 


Read either a single byte of data or a buffer of data from the file. 


File.seek 
Change the current file pointer position. 


bool seek(uint32 t pos, SeekMode mode) 
The mode can be one of: 
* SeekSet — Change the file pointer position to the absolute value. 
* SeekCur — Change the file pointer position to be relative to the current position. 


* SeekEnd — Change the file pointer position to be relative to the end of the file. 





File.size 
Retrieve the maximum size of the file. 


size t size() 


File.write 
Write data to the file. 


size t write(uint8 t c) 
size t write(uint8 t *buf, size t size) 


Write either a single byte or a buffer of bytes into the file at the current file pointer 
position. 
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Dir.fileName 
Retrieve the name of the file. 


String fileName() 


Dir.next 
bool next() 


Dir.open 
File open(const char *mode) 
File open(String &path, const char *mode) 


Dir.openDir 

Dir openDir(const char *path) 
Dir openDir (String &path) 
Dir.remove 


Dir. rename 


Arduino ESP library 


A class has been provided called ESP that provides ESP8266 environment specific 
functions. You must realize that using these functions will result in your applications not 


being portable to the Arduino (if that is a desire). 


ESP.eraseConfig 


bool eraseConfig() 


ESP. getChipld 
uint32 t getChipId() 


ESP. getCpuFreqMHz 
uint8 t getCpuFreqMHz () 





ESP. getCycleCount 
uint32 t getCycleCount () 





ESP. getFlashChipMode 
FlashMode t getFlashChipMode () 
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ESP. getFlashChipSize 
uint32 t getFlashChipSize() 


ESP. getFlashChipSpeed 
uint32 t getFlashChipSpeed () 





ESP. getFreeHeap 
uint32_t getFreeHeap () 


ESP. getOption 


int getOption(int option, int *value) 


ESP. getSdkVersion 
Retrieve the string representation of the SDK being used. 





const char *getSdkVersion () 


ESP. flashEraseSector 


bool flashEraseSector (uint32 t sector) 








ESP.flashRead 


bool flashRead(uint32 t offset, uint32_ t *data, size t size) 


ESP. flashWrite 
bool flashWrite(uint32 t offset, uint32 t *data, size t size) 


ESP. magicFlashChipSize 
uint32 t magicFlashChipSize(uint8 t byte) 


ESP. magicFlashChipSpeed 
uint32 t magicFlashChipSpeed(uint8 t byte) 


ESP. restart 


void restart () 
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Arduino String library 
Although it is believed that this library may be identical to the Arduino String library, | 
believe it is so essential to understand that | am going to list the methods again. 





String 

Constructor 

String(const char *cstr = ""); 

String(const String &str) 

String(char c) 

String(unsigned char, unsigned char base = 10) 
String(int, unsigned char base = 10) 
String(long, unsigned char base = 10) 
String(unsigned long, unsigned char base = 10) 
String(float, unsigned char decimalPlaces = 2) 
String(double, unsigned char decimalPlaces = 2) 


Create an instance of the String class seeded with various data type initializers. 


String.c_str 
Retrieve a C string representation. 


const char *c_str() 


String. reserve 
unsigned char reserve(unsigned int size) 


String.length 
Return the length of the string. 


unsigned int length () 


Return the length of the string. 


String.concat 


unsigned char concat(const String &str) 


unsigned char concat(const char *cstr) 


unsigned char concat(char c) 


unsigned char concat (unsigned char c) 


unsigned char concat (unsigned int num) 


unsigned char concat (long num) 


unsigned char concat (unsigned long num) 


unsigned char conca 


t ( 

t ( 

t ( 

t ( 
unsigned char concat (int num) 

t 

t ( 

t ( 

t (float num) 

t ( 





unsigned char concat (double num) 


String.equalslgnoreCase 
unsigned char equalsIgnoreCase(const String &s) const; 
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String.startsWith 
Determine whether or not this string starts with another string. 


unsigned char startsWith(const String &prefix) 
unsigned char startsWith(const String &prefix, unsigned int offset) 


String.endsWith 


unsigned char endsWith(const String &é&suffix) 


String.charAt 


char charAt (unsigned int index) 


String.setCharAt 


void setCharAt (unsigned int index, char c) 


String. getBytes 


void getBytes(unsigned char *buf, unsigned int bufsize, unsigned int index = 0) 


String toCharArray 


void toCharArray(char *buf, unsigned int bufsize, unsigned int index = 0) 





String.indexOf 
Find the position of a string or character within the current string. 


int indexOf(char ch) 

int indexOf (char ch, unsigned int fromIndex) 
int indexOf ( 
( 


int indexOf(const String &str, unsigned int fromIndex) 


const String &str) 


Find the position of a string or character within the current string. If the match is not 
found, -1 is returned otherwise the position of the start of the match is returned. 


String. lastIndexOf 


int lastIndexOf (char ch) 

int lastIndexOf (char ch, unsigned int fromIndex) 
int lastIndexoOf ( 
( 


int lastIndexOf (const String &str, unsigned int fromIndex) 


const String &str) 


String.substring 
Retrieve a substring from within the current string. 


String substring(unsigned int beginIndex) 
String substring(unsigned int beginIndex, unsigned int endIndex) 





Retrieve a substring from within the current string. 


String.replace 
void replace(char find, char replace) 
void replace(const Stringé& find, const String& replace) 


String. remove 
void remove (unsigned int index) 
void remove (unsigned int index, unsigned int count) 


String. toLlowerCase 
void toLowerCase (void) 
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String. toUpperCase 


void toUpperCase (void) 





String.trim 


void trim(void) 


String. tolnt 
long toInt (void) 





String.toFloat 
float toFloat (void) 


Reference materials 
There is a wealth of information available on the ESP32 from a variety of sources. 


Read-The-Docs 


Some of the best knowledge on the ESP32 comes from the Github source of the ESP- 
IDF. The project contains markup documentation that is hand written and also the 
source files are mechanically scanned. The result is some superb documentation that 
can be found here: 


http://esp-idf.readthedocs.io/en/latest/ 


C++ Programming 


Eclipse configuration 
To support the correct indexing of the standard templates, the following incantation is 
required. 


1. Open up the project properties 


. Visit C/C++ General > Preprocessor Include Paths, Macros, etc 


. Check the box for "CDT GCC Built-in Compiler Settings" 


. Set the compiler spec command to 
xtensa-esp32-elf-gcec S{FLAGS} -std=gnu+t+1ll -E -P -v -dD "S{INPUTS}" 


6. Rebuild the index 


2 
3. Select the Providers tab 
4 
5 
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Properties for cpp_helloworld 








@ Preprocessor Include Paths, Macros etc. = 
> Resource 
Builders Configuration: | Default [ Active] * | Manage Configurations... 
> C/C++ Build 
Vv C/C++ General 
> Code Analysis Entries | =Providers 
Documentation F 
@ } CDTUser Setting Entries Clear Entries 
File Types 5) : : 
Formather @ 2) Expo Entries from Referenced Projects [Shared ] Pacak 
mnidexer oR anaged Build Setting Entries [Shared] 
: & & CDT GCC Built-in Compiler Settings 
Language Mappin © a 7 . hared Move Up 
Paths and Symbol. Binary Debug Data Entries [Shared ] 
® CDT Cross GCC Built-in Compiler Settings [Shared ] Move Down 


Preprocessor Include Paths, Nv 2 
= . |=? CDT GCC Build Output Parser [Shared ] 

Profiling Categories _ 

Git Language Settings Provider Options 


Linux Tools Path Use global provider shared between projects Store entries in pr 
Project References 


Refactoring History Command to get compiler specs: 


eeoas [ktensa-espaz-elFgce S{FLAGS)-£-P-v-dD"S{INPUTS}” 
> Task Repository ktensa-esp32-elf-gcc ${FLAGS} -E -P -v -dD "S${INPUTS} 


Task Tags Allocate console in the Console View 
> Validation 


WikiText 


Restore Defaults Apply 











Simple class definition 

Classes are defined using the "class" keyword. Within a class we can define public 
fields and member functions as well as private fields and member functions. Public 
items may be accessed directly from outside the class if we have an instance of it. 
Private items may be accessed only from within the class itself. 


A constructor method is a public method having no return type and the same name as 
the class itself. Should we need to perform some specialized cleanup, we can declare a 
destructor method that is invoked when the class instance is deleted. The name of the 
method is the same as the class but prefixed with the "~" character and has no return 


type. 


Within a class instance methods, we can use a variable called this which will be an 
implicit pointer to the instance of the current class. 


If we declare a field within a class definition as being static, then just one copy of the 
variable is shared across all instances of the class. A method within a class can be 
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defined as static and is thus allowed to be executed without reference to a class 
instance. 


One class can inherit from another using: 


class newClass: public existingClass { 


Sample class header 


#ifndef MyClass h 
#define MyClass h 


class MyClass { 
public: 


MyClass (); 
static void myStaticFunc(); 
void myFunc(); 

}; 

#fendif 


Sample class source 


#include <MyClass.h> 
MyClass::MyClass() { 
// Constructor code here ... 
} 
String MyClass::myStaticFunc() { 
// Code here ... 


} 
void MyClass::myFunc() { 


// Code here ... 
} 


Mixing C and C++ 

The vast majority of the ESP-IDF platform is written in C. Should you wish to write C++ 
applications and leverage the ESP-IDF C functions or, conversely, have ESP-IDF 
application logic call your C++ source files there is an important consideration we have 
to include. 


In C, if | define a function, f00() for example, then the function is called foo() and there 
is no ambiguity. Now consider a class called a which has a function called foo() anda 
second class called 8 which also has a function called f00(). It Seems pretty obvious 
that | can't simply call £00() as the environment would not know which one was meant. 
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That is why we prefix a function call with the class name in which it was defined. Now 
let us consider functions declared outside of a class. For example: 


void bar() { 

// some code 
} 
If | coded this in a C++ program, | could then call bar () and all would be good. 
However if then wrote a C source file and tried to call bar() we might be surprised to find 
that the linker would complain that we couldn't find bar (). Why is this? 


The answer is that when we declare a global function in a C++ source file, the C++ 
environment implicitly flags the function as being part of a C++ class that represents 
some global class and, as such, its name is not actually bar () but is instead 


<someGlobalName>::bar(). 


Fortunately, should we wish, we can explicitly declare that a function definition should 
be defined without a prefix class name by using the syntax: 


extern "C" { 
void bar(); 


} 
This results in the exported name of bar () without any further decoration. 


Including stdc++ in your app 
The Espressif supplied C++ compiler includes the stdc++ library. If we wish to use this, 
we must include it in our linking. The easiest way to do this is to add 














COMPONENT ADD LDFLAGS=-lstdc++ -1$ (COMPONENT NAME) 





To component .mk in the main directory. 


C++ Specialized Data types 


String 
The string data type is included through: 


#include <string> 


A string can be declared using: 


std::string myString = "Hello World"; 

Since string is a class, we have objects available on it: 
* length / size — The length/size of the string in characters. 
* find -—Find a sub-string with the string. 


* empty — True if the string is empty. 
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* clear — Empty the string. 

¢ + —Concatenate to the string. 

* c str —Return a null terminate string representation (a C language string). 
The string type also has some powerful stream processors associated with it. 
There is a class called std::stringstream which allows us to stream data into it and 


then retrieve the string representation. For example: 


#include <sstream> 
std::stringstream stream; 

// do stream things 

std::string myString = stream.str(); 


We can append into the stream with: 

stream << "hello " << "world: " << 123; 

We can also do numeric formatting such as setting the width, fill character and hex 
mode: 


#include <iomanip> 
stream << std::setfill('0') << std::setw(2) << std::hex << 99; 


List 
The list data type is included through: 
#include <list> 


std::list<type> myList 


Map 
This data type stores name/value pairs. 


The map data type is included through: 


#include <map> 


We define a map variable using: 





std::map<keyType, valueType> mapName; 


To insert a value into the map we use: 


mapName.insert (std: :pair<keyType, valueType>(key, value)); 





To see if a value is within the map, we use: 


valueType value = mapName.at[key]; 
This will throw a std::out_of range exception if the key is not found in the map. 


To iterate through a map we use: 
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for (auto &myPair : mapName) { 
// myPair.second is the value 


} 
See also: 


std::map Tutorial Part 1: Usage Detail with examples 





Queue 
The queue data type is included through: 


#include <queue> 


Stack 
The stack data type is include through: 


#include <stack> 


Vector 
The vector data type is included through: 


#include <vector> 
and is part of the "std: :" namespace. 


std::vector<type> myVector; 
We can access the member's of a vector through the "[x}" array index construct. 


We can append to the end of a vector using "push back ()" and pull from the end using 
"pop back()". The size() method returns the number of entries in the vector. The 
clear () method removes all entities in the vector. The empty () method returns true if 
the vector is empty. 


Lambda functions 

Modern C++ has introduced lambda functions. These are C++ language functions that 
don't have to be pre-declared but can instead be declared "inline". The functions have 
no names associated with them but otherwise behave just like other functions. 


See also: 


Lambda functions 


Designated initializers not available in C++ 
In the latest versions of the C programming language, we can perform interesting 
structure initializations such as: 


Page 770 


struct myStruct myVar = { 
.a = 123; 
2b "xy"; 

he 


This will create an instance of a variable called "myvar" of type "struct myStruct" and 
initialize its members. 


This capability is not present in C++. 


Ignoring warnings 

From time to time, your code may issue compilation warnings that you wish to suppress. 
One way to achieve this is through the use of the C compile #pragma directive. 

For example: 

#pragma GCC diagnostic ignored "-Wformat" 

See also: 


GCC Diagnostic Pragmas 





Documenting your code - Doxygen 

For C and C++ source applications, the defacto standard for documentation is the 
Doxygen tool. Doxygen is big and rich and here we will capture a cheat sheet to get 
you going with working with your source. 


Doxygen is an application that has dependencies on another tool called "Graphviz". 
A GUI tool called "doxywizard" is available after installing "doxygen-gui" 
See also: 


Doxygen 
Graphviz 


Makefiles 

Books have been written on the language and use of Makefiles and our goal is not to 
attempt to rewrite those books. Rather, here is a cheaters guide to beginning to 
understand how to read them. 


A general rule in a make file has the form: 
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Largeur ‘prereqgs 
receipe ... 


Variables are defined in the form: 

name=value 

We can use the value of a variable with either $(name) or ${name}. 
Another form of definition is: 


name:=value 


Here, the value is locked to its value at the time of definition and will not be recursively 
expanded. 


Some variables have well defined meanings: 



































Variable Meaning 

CC C compiler command 
Cxx C++ compiler 

CFLAGS Flags for the C compiler 
CPPFLAGS Flags for the C++ compiler 
AR Archiver command 

LD Linker command 
OBJCOPY Object copy command 
OBJDUMP Object dump command 








We can use the value of a previously defined variable in other variable definitions. For 
example: 





XTENSA TOOLS ROOT ?= c:/Espressif/xtensa-1x106-elf/bin 
CC := $(XTENSA TOOLS ROOT) /xtensa-1x106-elf-gcec 








defines the C compiler as an absolute path based on the value of a previous variable. 
Special expansions are: 

¢ se@- The name of the target 

¢ s<- The first preregq 


Comments are lines that start with an "#" character. 














Wild cards are: 
e »*-All characters 
¢ ?-QOne character 
e [..] -Aset of characters 


Make can be invoked recursively using 
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make -C <directoryName> 


Imagine we wanted to build a list of source files by naming directories and the list of 
source files then becomes all the ".c" files, in those directories? How can we achieve 
that? 





SRC_DIR = dirl dir2 

SRC := $(foreach sdir, $(SRC_DIR), $(wildcard $(sdir)/*.c)) 
OBJ := $(patsubst %.c, $(BUILD BASE)/%.0, $(SRC)) 

The puzzle 


Imagine a directory structure with 


a 
alc 
a2Zec 


bie 
b23c 


goal is to compile these to 


build 


al.o 
a2.o 


bl.o 
b2.0 


We know how to compile x.c — x.o 


MODULES=a b 

BUILD_BASE=build 

BUILD DIRS=$ (addprefix $ (BUILD BASE) /,$ (MODULES) ) 
SRC=$ (foreach dir, $(MODULES), $(wildcard $(dir)/*.c)) 
# Replace all x.c with x.o 

OBJS=$ (patsubst %.c,%.0,$ (SRC) ) 

















all: 
echo $(OBJS) 
echo $(wildcard $(OBJS)/*.c) 
echo $(foreach dir, $(OBJS), $(wildcard $(dir)/*.c)) 
echo "SRC: " $(SRC) 


test: checkdirs $(OBJS) 
echo "Compiled " $(SRC) 
echo "Compiling $(basename $<)" 


$(CC) -c $< -o build/$(addsuffix .o, $(basename $<)) 


checkdirs: $ (BUILD DIRS) 
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$ (BUILD DIRS) : 
mkdir -p $@ 


clean: 
rm =f $ (BUILD DIRS) 


Makefiles also have interesting commands: 


* $§(shell <shell command>) — Runa shell command. 


° S(info "text"), $(error "text"), $(warning "text") — Generate output from 
make. 
See also: 
. GNU make 


. Makefile cheat sheet 





The component.mk settings 
Within the ESP-IDF environment, we have the component .mk build system. This uses 
specific variables for its configuration. 


For a component specific component .mk we have: 





* COMPONENT ADD INCLUDEDIRS — Directory to be added to the include path of the 
entire project. 











* COMPONENT PRIV_INCLUDEDIRS — Relative path to include directories that will only 
be used for module compilation. 





° COMPONENT DEPENDS — 











° COMPONENT ADD LDFLAGS — 














° COMPONENT EXTRA INCLUDES — 





























* COMPONENT sRcDIRS —A Set of of one or more directories relative to the location of 
the component which are expected to contain source files. The files contained in 
these directories will be compiled and included in the resulting library. 





* COMPONENT oBJs — The set of object files that we need as a target. 

















° COMPONENT EXTRA CLEAN — 





° COMPONENT BUILDRECIPE — 














° COMPONENT CLEANRECIPE — 



































° COMPONENT BUILD DIR— 
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COMPONE 























COMPONENT EMBED FILES — This takes a list of binary files that are then added into 
the application. The start of the data in flash that corresponds to the file data is 
then exposed as a linker symbol. The same is also true for the last byte of the 
file giving two symbols in total. For example, if we were to embed a file called 
"mydata.dat", we might use: 














NT EMBED FILES:= mydata.dat 





This would produce two new symbols called binary mydata dat start and 
_binary mydata dat end. These could then be used in an application by using: 


extern 
extern 


uint8 t mydata_ dat _start[] asm("_ binary mydata_dat_start"); 
uint8 t mydata_dat_end[] asm(" binary mydata dat end"); 
































COMPONENT EMBED TXTFILES — This is identical to COMPONENT EMBED FILES except that 
a NULL Character is added at the end of the data to produce a NULL terminated string. 
This might be used if the file contained character data. 

crLacs — Use this setting to change C compiler flags passed to the module. Take 
care to realize that the environment already passes in flags so don't use absolute 
settings. Instead use "cFrLAGS+=<value>" to maintain the existing values while 


adding new ones. 




















See also: 


Adding a custom ESP-IDF component 


Forums 
There are a couple of excellent places to ask questions, answer other folks questions 
and read about questions and answers of the past. 


ESP32 Community Forum — The ESP32 community forum where all discussions of ESP32 are happening. 





Reference documents 
Espressif distributes PDF and Excel spreadsheets containing core information about the 
ESP32. These can be downloaded freely from the web. 


ESP-WROOM-32 Datasheet — 2016-08-22 
ESP32 Technical Reference Manual 
ESP32 Datasheet 

ESP32_RTOS_SDK 

ESP32 Pin List — V2.0 

ESP32 RTOS SDK API Reference v1.1.0 
ESP-IDF Getting Started Guide 

ESP32 AT Instruction Set and Examples 
Mastering the FreeRTOS real time kernel 
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Github 

There are a number of open source projects built on top of and around the ESP8266 
that can be found on Github. Here is a list of links to some of these projects that are 
very well worth having a look: 


* espressif/esp-idf - The ESP-IDF ... without this we would have little to talk about. 


* espressif/esp-idf-template — The template application from which we build new 
applications. 





* espressif/arduino-esp32 — The Arduino environment for the ESP32. 





Github quick cheats 

When working with open source projects, there are times when we would like to perform 
some tasks that involve multiple commands. Here we try and capture some of the more 
interesting ones that are used in ESP32 projects from time to time. 


git remote -v 

git remote add upstream <URL> 
git fetch upstream 

git merge upstream/master 


To create a new repository in Github from a directory of goodies, do the following. 
1. Create a new github repository 

echo "# <repository name>" >> README.md 

git init 

git add README.md 

git commit -m "first commit" 


git remote add origin https://github.com/<repository>.git 


ay ee ot ee ee. IS 


git push -u origin master 
See also: 


Simple guide to forks in GitHub and Git 





Installing Ubuntu on Virtual Box 

| have a personal preference on the environment on which | perform development. | like 
to program on a Linux environment. | use Microsoft Windows for all my desktop work 
including document editing, browsing, email and much, much more ... however when it 
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comes to programming, | like Linux. | do not want you to believe that in order to work 
with the ESP32 that you must use Linux ... that is simply not true. However, if you do 
decide that you want to use Linux then you will need a Linux environment. Historically, 
one would load an operating system on a machine and that would be the end of the 
story. One machine equals one operating system. Thankfully, those days are past and 
we can now adopt virtual machines. A virtual machine is a logical machine that runs as 
a "guest" under a host operating system. In our story, we want a virtual Linux machine 
running as a guest on a Windows or MacOS host. There are many fine vendors of 
virtual machine technology. The one | have chosen to illustrate in this story is 
VirtualBox from Oracle. This is an open source implementation that is free for us to use. 


Let us now look at the steps necessary to get a Linux environment up and running for 
ESP32 development. | will assume that you have downloaded and installed the latest 
VirtualBox. Next we need an image of Linux to install. Personally, | use Ubuntu 
Desktop which can be downloaded here. The end result of the download will be a file 
about 1.5GBytes in size. At the time of writing, the download was called "ubuntu- 
16.04.2-desktop-amd64.iso". The file is an image of a DVD that could be burned and 
installed from physical media however we don't need to do that, we can install directly 
from this image. 


1. Launch VirtualBox 


2. Click "New" to create a new Virtual Machine 


aG i 


New Settings Discard Show 
64 PC9100 =) Gener 


3. Give ita name (eg. "ESP32Linux") and specify its type (Linux) and version 
(Ubuntu 64Bit) 





7 


% 
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Create Virtual Machine 


Name and operating system | 


Please choose a descriptive name for the new virtual machine and select 
the type of operating system you intend to install on it. The name you 
choose will be used ua "aus to identify this machine. | 


Name: |ESP32Linux — 
Type: Linux “— = ‘Sp 
Version: Ubuntu (64-bit) ~ 

















Expert Mode Next Cancel | 











Click "Next" to continue. 


4. Specify how much RAM you want to give the machine. 





© _ Create Virtual Machine 


Memory size | 


Select the amount of memory (RAM) in megabytes to be allocated to the 
virtual machine. 


The recommended memory size is 1024 MB. | 





[4096] mB 
4MB 14336 MB 











Next Cancel | 











5. Create a virtual disk 
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© Create Virtual Machine 


Hard disk 


If you wish you can add a virtual hard disk to the new machine. You can 
either create a new hard disk file or select one from the list or from 
another location using the folder icon. 


If you need a more complex storage set-up you can skip this step and 
make the changes to the machine settings once the machine is created. 


The recommended size of the hard disk is 8.00 GB. 


© Do not add a virtual hard disk a 


© Create a virtual hard disk now 
© Use an existing virtual hard disk file 


PC9100-2.vdi (Normal, 60.00 GB) 


Create Cancel 




















| Create Virtual Hard Disk 

Hard disk file type 

Please choose the of file that you would like to use for the new virtual hard disk. If you 
do not need,t with other virtualization software you can leave this setting unchanged. 
@) VDI (VirtualBox Disk Image) 


© VHD (Virtual Hard Disk) 
© VMDK (Virtual Machine Disk) 








Expert Mode Next Cancel 











Page 779 








space on it is freed. 


use. 


O Fixed size 


© Create Virtual Hard Disk 


Storage on physical hard disk 


Please choose whether the new virtual hard disk file should grow as it is used (dynamically 
allocated) or if it should be created at its maximum size (fixed size). 


A dynamically allocated hard disk file will only use space on your physical hard disk as it 
fills up (up to a maximum fixed size), although it will not shrink again automatically when 


A fixed size hard disk file may take longer to create on some systems but is often faster to 


@) Dynamically allocated 














| 6% PC9100-2 
@ Powered Off 


CO ESP32Linux 
a (7) Powered Off 








Next Cancel 
6. Start the Virtual Machine 

Oracle VM VirtualBox Manager N 

File Machine Help 

New Settings Discard Start 

64) | pc9100 =) General 
= Running . 
| Name: ESP32Linux 
| (6a cP Operating System: Ubuntu (64-bit) 

@ Powered Off “| System 


Base Memory: 4096 MB 
Boot Order: Floppy, Optical, Hard Disk 
_ Acceleration: VT-x/AMD-V, Nested Paginc 


_& Display 
Video Memory: 17 MB 
Remote Desktop Server: Disabled 
_ Video Capture: Disabled 








Storage 





7. Select the Linux installation image 
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Select start-up disk 


Please select a virtual optical disk file or a physical optical drive 
containing a disk to start your new virtual machine from. 


The disk should be suitable for starting a computer from and 
should contain the operating system you wish to install on the 
virtual machine if you want to do that now. The disk will be 
ejected from the virtual drive automatically next time you switch 
the virtual machine off, but you can also do this yourself if 
needed using the Devices menu. 


ubuntu-16.04.2-desktop-amd64.iso (1.45 GB) "| q 


Start Cancel 

















8. Install Linux 


The installation of Ubuntu Linux will now start and take some time to complete. Ten 
minutes seems to be about average. 


9. Reboot and be in Linux. 


Reboot the virtual machine and you will find that you have a Linux environment in which 
to work. 
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| a on Be ; 
| [A ESP32Linux [Running] - Oracle VM VirtualBox = x 














[File Machine View Input Devices Help 



























28 SOS LESwBrintcn . 








You can now customize the environment as you wish. Typically | remove the items | 
don't want from the task bar including FireFox, Libre Office, Ubuntu Software and 
Amazon. 


When you plug in an ESP32 to the USB port of a machine running Virtual Box, you may 
also have to tell Virtual Box to "own" the USB—UART ... in the Devices—USB settings 
you can see a list of USB devices to add: 
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Oracle VM VirtualBox 
Input Devices Help 
©) Optical Drives 
S * i Network My @vy Bry Bry ®viGr Bry Gr Gritr Ovr' 
er & 5 USB Settings... fae 
Web ngtt 
sit bs = ae 6 Cubeternet [0101] 
S F » 
1p180 [ eee QinHeng Electronics USB2.0-Serial [0254] ts_t 
np1s0_ |_| Shared Clipboard 7 Generic USB2.0-CRW [5195] ) ¢ 
bh = 
iia =§ Drag and Drop > Saleae LLC Logic 
np1801 gf Insert Guest Additions CD image... Northstar System Corp. eHome Infrared Transceiver [0117] k, ¢ 
citadel tea Logitech USB Receiver [1203] gs" 
master] ss ' 
coiabiailall Logitech USB Keyboard [6400] 
A Generic Ultra Fast Media Reader [0190] 

. le FTDI FT231X USB UART [1000] 

TT 118¢77" 





Its been my experience | have to re-add it here each time after powering on the Virtual 
Box. 


Single board computer comparisons 

There are a number of single board computers on the market. Although the ESP8266 is 
usually not considered one of these, a lot of folks are using it as such. Let us put up a 
table and contrast the ESP32 against these computers: 


























Device |CPU RAM Flash | Wifi GPIO OS Cost 
ESP8266 | 830MHz 80K 512K |Y 9 FreeRTOS $4 
ESP32 160MHz 512K Var Y ? FreeRTOS 2? 
Arduino |20MHz 2K 32K IN ? N/A $2 
PiZero | 1GHz 512MB_ _|SD N ? Linux $5 
Omega | 400MHz 64MB 16MB |Y 18 Linux $19 
Omega 2 

C.H.LP. | 1GHz 512MB |4GB |Y 8+ Linux $9 
































Areas to Research 
¢ Hardware timers ... when do they get called? 
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If | define functions in a library called libcommon.a, what is added to the compiled 
application when | link with this library? Is it everything in the library or just the 
object files that are referenced? 


How much RAM is installed and available for use? 


Document the information contained here ... 
http://obs.espressif.com/viewtopic.php?p=3066#p3066 


What is SSDP and how does it related to the SSDP libraries? 


Study Device Hive - http://devicehive.com/ 








Document using Visual Micro debugger with Visual Studio. 
http:/Awww.visualmicro.com/ 
Power management 


Research the semantics of a wifi_station_connect() when we are already 
connected. 


Look at using libssh2 as a library in ESP32 
In power management — what is RTC? 

In power management — what is ULP? 
Study loT.js 


Look at the GDB post here ... interesting subcommand . 
http://esp32.com/viewtopic.php?f=2&t=767 
How do we set a static IP address for the ESP32 when it is an access point? 


research micro sd APIs 

Study the following http://esp32.com/viewtopic.php?f=138&t=924#p3997 
Write about UDP broadcasting 

Add a section on MCP23017 port expander. 

Study iot.espressif.cn 

Study http://platformio.org/ 

Video: Push button interrupts 

Video: Build from scratch — ESP-IDF, compilers etc etc 


Touchpad support 


Document the following http://esp-idf.readthedocs.io/en/latest/build- 
system.html#embedding-binary-data 


¢ Do a video on watchdog processing 

¢ What is WiFi promiscuous mode? 

¢ Document how to compile JerryScript 

¢ Document how to compile Duktape 

¢ Write an APDS-9330 C++ class 

¢ Add task management methods to the CPP class 


¢ Examine the mDNS responder from apple as a possible port ... 
https://opensource.apple.com/source/mDNSResponder/ 
¢ Write and test instructions for building nrf24 on ESP32 


¢ Implement partition logging in C++ 

¢ Build samples using ADX345 IC. 

¢ What is Apple iBeacon? 

¢ Write BLE CPP code for GATT. 

¢ Write up the AWS support. 

¢ Retest the mDNS support now that we have extra patches. 
¢ test out the new I2C OLED displays with ugZlib 

¢ study grpc 

° Stu 


Things to buy 
* BME280 
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